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Preface 



This publication contains quick reference informa- 
tion on the data management and system control 
macros for the experienced programmer and systems 
support personnel. For the most part, restrictions 
and programming details have been omitted in order 
to provide rapid access to the information in this 
publ>ation. If the information included herein is 
not sufficient for your purposes, refer to the books in 
the following publications list. 

DOS/VSE Data Management Concepts, GC24-5138 



DOS/VSE System Management Guide, GC33-5371 

OS/VS - DOS/VSE - VM/ 370 Assembler 
Language, GC33-4010 

Introduction to DOS/VSE, GC33-5370 

DOS/VSE System Control Statements, GC33-5376 

DOS/ VSE Serviceability Aids and Debugging 
Procedures, GC33-5380 

This publication is divided into five chapters. The 
first chapter contains a list of the macros described 
later in the book showing their formats and listing 
the operands permitted for each. The list also con- 
tains a succinct description of each macro's function 
and the number of the page where the detailed de- 



scription of the macro may be found. The macros 
are listed in alphabetical order within the chapter, 
which serves as an index for the remainder of the 
book. 

Chapter 2 contains an explanation of the macro 
notation used in this book. 

Chapter 3 contains the descriptions of the declara- 
tive macros; Chapter 4 contains the imperative mac- 
ros; Chapter 5 contains the system control macros. 
These chapters describe the macros in detail. With 
the following exceptions, the macros are arranged in 
alphabetic order within each chapter: 

• The logic module generation (xxmod) macros 
follow the DTFxx macros with which each is 
associated; for instance, PRMOD follows imme- 
diately after DTFPR. 

• The line type macros, DFR and DLINT, follow 
immediately after DTFDR and DRMOD, with 
which they are associated. 

Some of the information included in this book ap- 
plies only to systems on which v$E/Advanced Func- 
tions is installed. In those cases, the VSje/ Advanced 
Fxinctioiis material is lightly shaded for easy identl- 
fkration. 
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Chapter 1: Data Management and System Control Macro Formats 



Name Operation 

[name] ATTACH 



[name] CALL 

[name] CANCEL 
[name] CCB 



[name] CDLOAD 
[name] CDMOD 



[name] CHAP 
[name] CHECK 

[name] CHKPT 



[name] (CLOSE] 
CLOSER} 

[name] CNTRL 



[name] COMRG 
Inaffiel CPCLOSE 

[name] (DAMOD| 
DAMODV} 



[name] DEQ 
[name] DETACH 



Operands Use Page No. 

{entrypoint|(S,entrypoint)|(rl)} Initiates a subtask 5-1 

,SAVE=(savearea|(S,savearea)|(r2)) 
[,ECB= {ecbn2rme|(S,ecbname)|(r3)} ] 
[,ABSAVE= {savearea|(S,savearea)|(r4)} ] 
[,MFG=^ (areal(S,area)|(r5)} ] 

{entrypoint|(15)) Passes control to a specified entry point in another program ... 5-2 

[,(parameterlist)] 

[ALL] Terminates a task or sub-task 5-2 

SYSnnn Defines an IOCS command control block 4-1 

,command-list-name 

[,X'nnnn'] 

[,senseaddress] 

{phasename|(l)} Loads a specified phase into the partition GETVIS area 5-3 

[,PAGE=YES] 

[CONTROL=YES] Defines a logic module for a card reader file 3-6 

[,CRDERR=RETRY] 

[,CTLCHR=(ASA|YES)] 

[,DEVICE=nnnn] 

[,FUNC= (R|P|I|RP|RW|RPW|PW}] 

[,IOAREA2=YES] 

[,RDONLY=YES] 

[,RECFORM= (FIXUNB IVARUNBIUNDEF) ] 

[,SEPASMB=YES] 

[,TYPEFLE= (INPUT IOUTPUTICMBND) ] 

[,WORKA=YES] 

Lowers the priority of the issuing subtask 5-3 

(filename|(l)} Prevents processing until I/O data transfer is complete 4-5 

[,control-addrj(0)] 

SYSnnn Records the status of your program for later restarting 5-3 

, {restart-addr|(rl)} 

[,end-addrl,(r2)] 

[,tpointer|(r3)] 

[,dpointer|(r4)] 

[,filename|(r5)] 

(filename 1 1 (rl)} Deactivates a file 4-8 

[,filename21,(r2)]... 

(filename|(l)} Provides non-data device commands 4-8 

,code 
[,nl][,n2] 

[REG=nn] Places the partition's communication 

region address in register nn 5-4 

|8iglistf<El>3 rs&iises a CK3LOSE c<mmiajMl to VM/370 

to irelesse e pnni atpinch fSe lof oatpat ^,^ + .... 5-4 

[AFTER=YES] Defines a logic module for a direct access file 3-15 

[,ERREXT=YES] 

[,FEOVD=YES] 

[,HOLD=YES] 

[,IDLOC=YES] 

[,RDONLY=YES] 

[,RECFORM=xxxxxx] 

[,RELTRK=YES 

[,RPS=SVA] 

[,SEPASMB=YES] 

(rcbname|(0)} Releases an ENQ'ed resource 5-4 

[SAVE={savearea|(l)}] Terminates (normally) a subtask «« 5-5 
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Name 

[name] 



Operation 

DFR 



fnamol niMOn 



[name] DISEN 
[name] DLINT 



[name] DRMOD 

[name] DSPLY 
[name] DTFCD 



[name] DTFCN 



[name] DTFDA 



Operands 

FONT=xxxx 

[,REJECT=YES] 

[,ERASE=YES] 

[,CHRSET=n] 

[,EDCHAR=(x,...)] 

[,BCH=n] 

[,BCHSER=n] 

[,NATNHP=YES] 

rirk A t> C A T — VECl 

[,RDONLY=YES] 

[,RPS=SVA] 

[,SEPASMB=YES] 

[,TRC=YES] 

[,TYPEFLE= {OUTPUTjINPUT} ] 

(filename! (1)} 

LFR=nn,LINBEG=nn 

[,IMAGE=YES] 

[,NOSCAN=(n,n)] 

[,FLDn=(n,n,NCRIT,xxx)] 

[,EDITn=(xxxxxx,EDCHAR)] 

[,FREND=YES] 

[DEVICE=3886] 
[,RDONLY=YES] 
[,SEPASMB=YES] 
[,SETDEV=YES] 

(filename|(l)} 
,(r2),(r3) 

DEVADDR=SYSxxx 
IOAREA=xxxxxxxx 
,ASOCFLE=xxxxxxx] 
,BLKSIZE=nnn] 
,CONTROL=YES] 
,CRDERR=RETRY] 
,CTLCHR=xxx] 
,DEVICE=nnnn] 
,EOFADDR=xxxxxxxx] 
,ERROPT=xxxxxx] 
,FUNC=xxx] 
,IOAREA2=xxxxxxx] 
,IOREG=(nn)] 
,MODE=xx] 

,MODNAME=xxxxxxxx] 
,OUBLKSZ=nn] 
,RDONLY=YES] 
,RECFORM=xxxxxx] 
,RECSIZE=(nn)] 
,SEPASMB=YES] 
,SSELECT=n] 
,TYPEFLE=xxxxxx] 
,WORKA=YES] 

DEVADDR=SYSxxx 

JOAREA 1 =xxxxxxxx 

[,BLKSIZE=nnn] 

[,INPSIZE=nnn] 

[,MODNAME=xxxxxxx] 

[,RECFORM=xxxxxx] 

[,RECSIZE=(nn)] 

[,TYPEFLE=xxxxxx] 

[,WORKA=YES] 

BLKSIZE=nnnn 
,DEVICE=nnnn 
,ERRBYTE=xxxxxxxx 
JOAREA 1 =xxxxxxxx 



Use 

Defines attributes common to a group of line types 



Page No. 

.....3-25 



Bcuncs a logic module for a device-independent tile 3-20 



Stops feeding documents through MICR or OCR devices .... 4- 10 
Describes line types, fields in the line 3-27 



Defines logic modules for a 3886 file 3-24 

Displays document field on 1287 display scope 4-10 

Defines a card or 3881 file 3-1 



Defines a console file 3- 



Defines a direct access file 3-10 
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Name Operation 



[name] DTFDI 



[name] DTFDR 



Operands 

,SEEKADR=xxxxxxxx 
TYPEFLE=xxxxxx 
;,AFTER=YES] 
:,CONTROL=YES] 
;,DEVADDR=SYSnnn] 
,ERREXT=YES] 
:,FEOVD=YES] 
[,HOLD=YES] 
;,DSKXTNT=n] 
,IDLOC=xxxxxxxx] 
,KEYARG=xxxxxxx] 
^,KEYLEN=nnn] 
,LABADDR=xxxxxxxx] 
,MODNAME=xxxxxxx] 
,RDONLY=YES] 
;,READID=YES] 
;,READKEY=YES] 
,RECFORM=xxxxxx] 
;,RECSIZE=(nn)] 
[,RELTYPE=xxx] 
:,SEPASMB=YES] 
:,SRCHM=YES] 
,TRLBL=YES] 
[,VERIFY=YES] 
;,WRITEID=YES] 
;,WRITEKY=YES] 
;,XTNTXIT=xxxxxxxx] 

DEVADDR=SYSxxx 

,10 AREA 1 =xxxxxxxx 

[,CISIZE=n] 

[,EOFADDR=xxxxxxxx] 

[,ERROPT=xxxxxxxx] 

[,FBA=YES] 

[,IOAREA2=xxxxxxxx] 

[,IOREG=(nn)] 

[,MODNAME=xxxxxxxx] 

[,RDONLY=YES] 

[,RECSIZE=nnn] 

[,SEPASMB=YES] 

[,TRC=YES] 

[,WLRERR=xxxxxxxx] 

DEVADDR=SYSxxx 

,FRNAME=xxxxxxxx 

,FRSIZE=nn 

,EXITIND=xxxxxxxx 

,IOAREA 1 =xxxxxxxx 

,HEADER=xxxxxxxx 

,EOFADDR=xxxxxxxx 

,COREXIT=xxxxxxxx 

[,DEVICE=3886] 

[,RDONLY=YES] 

[,MODNAME=xxxxxxx] 

[,BLKSIZE=nnn] 

[,SEPASMB=YES] 

[,SETDEV=YES] 



Use 



Page No. 



Defines a device-independent file 3-17 



Defines a 3886 OCR file 3-21 
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Name Operation 

fnamel DTFDU 



[name] DTFIS 



[name] DTFMR 



[name] DTFMT 



Operands 

EOFADDR=xxxxxxxx 

,IOAREA 1 =xxxxxxxx 

,RECSIZE=nnn 

[,CMDCHN=nn] 

[,DEVADDR=SYSxxx] 

[,DEVICE=3540] 

[,ERREXT=YES] 

[,ERROPT=xxxxxxxx] 

[,FEED=xxx] 

[,FILESEC=YES] 

[,IOAREA2=xxxxxxxx] 

[,IOREG=(nn)] 

[,MODNAME=xxxxxxxx] 

[,RDONLY=YES] 

[,SEPASMB=YES] 

f TYPEFLE=xxxxxxi 



Use 

Defines a diskette file 



Page No. 

3-29 



[,VOLSEQ=YES] 
[,WORKA=YES] 
[,WRTPROT=YES] 

DSKXTNT=n 

,IOROUT=xxxxxx 

,KEYLEN=nnn 

,NRECDS=nnn 

,RECFORM=xxxxxx 

,RECSIZE=nnnn 

[,CYLOFL=nn] 

[,DEVICE=nnnn] 

[,ERREXT=YES] 

[,HINDEX=nnnn] 

[,HOLD=YES] 

[,INDAREA=xxxxxxxx] 

[,INDSKIP=YES] 

[,INDSIZE=nnnnn] 

[,IOAREAL=xxxxxxxx] 

[,IOAREAR=xxxxxxxx] 

[,IOAREAS=xxxxxxxx] 

[,I0AREA2=xxxxxxxx] 

[,IOREG=(nn)] 

DEVADDR=SYSnnn 

JOAREA 1 =xxxxxxxx 

[,ADDAREA=nnn] 

[,ADDRESS=DUAL] 

[,BUFFERS=nnn] 

[,ERROPT=xxxxxxxx] 

[,EXTADDR=xxxxxxxx] 

[,IOREG=(nn)] 

[,MODNAME=xxxxxxxx] 

[,RECSIZE=nnn] 

[,SECADDR=SYSnnn] 

[,SEPASMB=YES] 

[,SORTMDE=xxx] 

BLKSIZE=nnnnn 

,DEVADDR=SYSxxx 

,EOFADDR=xxxxxxxx 

,FILABL=xxxx 

JOAREA 1 =xxxxxxx 

[,ASCII=YES] 

[,BUFOFF=nn] 

[,CKPTREC=*YES] 

[,ERREXT=YES] 

[,ERROPT=xxxxxxxx] 

[,HDRINFO=YES] 

[,I0AREA2=xxxxxxxx] 

[,IOREG=(nn)] 

[,LABADDR=xxxxxxxx] 



Defines a indexed-sequential file 3-34 



Defines a MICR/OCR file 3-44 



Defines a magnetic tape file 3-46 
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Name Operation 



[name] DTFOR 



[name] DTFPH 



[name] DTFPR 



Operands 

[,LENCHK=YES] 

[,MODNAME=xxxxxxxx] 

[,NOTEPNT=xxxxxx] 

[,RDONLY=YES] 

[,READ=xxxxxxx] 

[,RECFORM=xxxxxx] 

[,RECSIZE=nnnn] 

[,REWIND=xxxxxx] 

[,SEPASMB=YES] 

[,TPMARK=[YES|NO] 

[,TYPEFLE=xxxxxx] 

[,VARBLD=(nn)] 

[,WLRERR=xxxxxxxx] 

[,WORKA=YES] 

COREXIT=xxxxxxxx 

,DEVADDR=SYSnnn 

,EOFADDR=xxxxxxxx 

,10 AREA 1 =xxxxxxxx 

[,BLKFAC=nn] 

[,BLKSIZE=nn] 

[,CONTROL=YES] 

[,DEVICE=xxxxx] 

[,HEADER=YES] 

[,HPRMTY=YES] 

[,I0AREA2=xxxxxxxx] 

[,IOREG=(nn)] 

[,MODNAME=xxxxxxxx] 

[,RECFORM=xxxxxx] 

[,RECSIZE=(nn)] 

[,SEPASMB=YES] 

[,WORKA=YES] 

TYPEFLE=xxxxxx 

[,ASCII=YES] 

[,CISIZE=n] 

[,CCWADDR=xxxxxxxx] 

[,DEVICE=xxxx] 

[,DEVADDR=SYSxxx] 

[,HDRINFO=YES] 

[,LABADDR=xxxxxxxx] 

[,MOUNTED=xxxxxx] 

[,XTNTXIT=xxxxxxxx] 

DEVADDR=SYSxxx 
10 AREA 1 =xxxxxxxx 
,ASOCFLE=xxxxxxxx] 
,BLKSIZE=nnn] 
,CONTROL=YES] 
:,CTLCHR=xxx] 
:,DEVICE=nnn] 
,ERROPT=xxxxxxxx] 
:,FUNC=xxxx] 
, lO AREA2=xxxxxxxx] 
;,IOREG=(nn)] 
,MODNAME=xxxxxxxx] 
:,PRINTOV=YES] 
,RDONLY=YES] 
;,RECFORM=xxxxxx] 
:,RECSIZE=(nn)] 
:,SEPASMB=YES] 
,STLIST=YES] 
,TRC=YES] 
,UCS=xxx] 
,WORKA=YES] 



Use 



Page No. 



Defines a 1287 or 1288 optical reader file 3-53 



Defines a Physical IOCS file 3-58 



Defines a printer file 3-61 
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Name Operation 

[name] DTFPT 



[name] DTFSD 



[aame] DIT 



[name] DUMOD 



[name] DUMP 

[name] ENDFL 

[name] ENQ 

[name] EOJ 

[name] ERET 

[name] ESETL 

[name] EXCP 



Operands 

BLKSIZE=n 

,DEVADDR=SYSnnn 

,IOAREA 1 =xxxxxxxx 

[,EOFADDR=xxxxxxxx] 

[,DELCHAR=X'nn'] 

[,DEVICE=nnnn] 

[,EORCHAR=X'nn'] 

[,ERROPT=xxxxxxxx] 

[,FSCAN=xxxxxxxx] 

[,FTRANS=xxxxxxxx] 

[,IOAREA2=xxxxxxxx] 

[,IOREG=(nn)] 

[,LSCAN=xxxxxxxx] 

[,LTRANS=xxxxxxxx] 

[,MODNAME=xxxxxxxx] 

f,OVBLKSZ=ni 

[,RECFORM=xxxxxx] 

[,RECSIZE-(nn)] 

[,SCAN=xxxxxxxx] 

[,SEPASMB=YES] 

[,TRANS=xxxxxxxx] 

[,WLRERR=xxxxxxxx] 

BLKSIZE=nnnn 

,EOFADDR=xxxxxxxx 

,10 AREA 1 =xxxxxxxx 

[,CISIZE=nnnn] 

[,CONTROL=YES] 

[,DELETFL=NO] 

[,DEVADDR=SYSnnn] 

[,DEVICE=nnnn] 

[,ERREXT=YES] 

[,ERROPT=xxxxxxxx] 

[,FEOVD=YES] 

[,HOLD=YES] 

[,IOAREA2=xxxxxxxx] 

[,IOREG=(nn)] 

[,LABADDR=xxxxxxxx] 

[,MODNAME=xxxxxxxx] 

[,NOTEPNT=xxxxxxx] 

[,PWRITE=YES] 

[,RDONLY=YES] 

[,RECFORM=xxxxxx] 

[NAME=fesourcefta«a«3 
J,CONTROL'= (S}S} 

l,OWK£a»= emSKfFARTITlON) } 

ERREXT=YES 
,ERROPT=YES 
(,RDONLY=YES} 
(,SEPASMB=YES) 



{filenamel(O)} 
{rcbname|(0)} 

(SKIP IIGNQREIRETRY) 



Use 

Defines a paper tape file 



Page No. 

3-67 



Defines a sequential DASD file 3-73 



{filename|(l)} 

{blockname|(l)} 
[,REAL] 



[name] EXIT {PC|IT|OC:AB|MRjTT} 
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Geoerates a. DTL ^define The Lock>coatrf>l block 

at assembly tsat , , , ^ . 5*5 

Defines a logic module for a diskette file 3-33 

Produces a hexadecimal dump 5-5 

Ends the mode initiated by SETFL .4-10 

Protects a resource 5-6 

Ends a job step or subtask 5-6 

Returns control from your error-processing 

routine to IOCS 4-10 

Ends sequential mode initiated by SETL 4-10 

Request PIOCS to start an I/O operation 4-11 

Returns control from your interrupt-checking routine 5-6 



Name 


Operation 


Operands 


[name] 


FCEPGOUT 


( (listname|( 1)} |beginaddr,endaddr| 
[beginaddr,endaddr]} 


[name] 


FEOV 


(filenamel(l)} 


[name] 


FEOVD 


{filename|(l)) 


[name] 


FETCH 


{phasename|(S,addr)|(l)} 

[,entrypoint|(S,entrypoint|(0)] 

[,LIST={listname|(S,listname)|(rl)}] 

[,SYS=YES] 

[,DE=YES] 

[,MFG= (area|(S,area)|(r2)} ] 


[name] 


FREE 


(filenamel(l)) 



[name] FREEVIS 



[name] GENDTL 



[name] GENIORB 



[name] GENL 

[name] GET 

[name] GETIME 

[name] GET VIS 

[name] lORB 



[name] ISMOD 



[ADDRESS=(namel|(l)}] 
[,LENGTH= (name2|(0)} ] 
[,SVA=YES] 

[ADDR= {namel|(S,namel)|(rl)) ] 

[,N AME= {name2|(S,name2)|(r2)} ] 

[,CONTROL={E|S)] 

[,L0CK0PT={JI|2)] 

[,KEEP=(N01YES}] 

[,OWNER= (TASK| PARTITION} ] 

[,LENGTH=(NO|YES}] 

[ADDRESS= (name 1 |(S,name 1 )|( 1 )} i 

[,LENGTH=fieldlength] 

,CCW= {name2|(S,name2)|(r2)} 

,(DEVICE=SYSxxx| 

L0GUNIT=(name3| 

(S,name3)|(r3)}) 

[,F1XLIST= {name4|(S,name4)|(r4)} ] 

[,FIXFLAG=(optionll,...)] 

[,IOFLAG=(option21,...)] 

[,ERREXT= (name5|(S,name5)|(r5)) ] 

[,ECB= (name6|(S,name6)|(r6)}] 

phasename 1 , phasename2, . . . 

[(,ADDRESS=(areal(S,area)l(rl)) 

,LENGTH=number}] 

[ (,ADDRESS= {DYNjDYNAMIC 

[,ERREXT= (addr!(S,addr)|(r2)) ]) ] 

(filename 1(1)} 
[,workname|,(0)] 

[STANDARD|BINARY|TU] 

[,LOCAL|GMT] 

[,MFG= {area|(S,area)|(r)} ] 

[ADDRESS= {name 1 1(1)}] 

[,LENGTH={name2|(0)}] 

[,PAGE=YES] 

[,POOL=YES] 

[,SVA=YES] 

DSECT=YES 

or 

CCW=namel,DEVICE=SYSxxx 

[,ECB=name2] 

[,FIXLIST=name3] 

[,FIXFLAG=(option U,...)] 

[,IOFLAG=(option21,...)] 



Use Page No. 

Forces an area to be paged out 5-7 

Forces end-of-volume for magnetic tape file 4-11 

Forces end-of-volume for DASD file 4-11 

Loads a phase; transfers control to it 5-8 



Makes available to other tasks a previously held 

track or CI 5-8 

Releases blocks of virtual storage previously obtained 

by a GETVIS 5-9 

Generates a DTL (Define The Lock) control block at 

executed time 5-9 



Generates an I/O Request Block at execution time 4-12 



Generates a local directory list in the partition 5-9 



Obtains the next sequential logical record from 

an input file 4-12 

Obtains the time of day 5-10 

Obtains a block of virtual storage from a GETVIS area 5-10 

Generates an I/O Request Block at assembly time 4-13 



[CORDATA=YES] 

[,CORINDX=YES] 

[,ERREXT=YES] 

[,HOLD=YES] 

[,I0AREA2=YES] 

,IOROUT=LOAD|ADD|RETRVE|ADDRTR 



Defines a logic module for an indexed sequential file 3-41 
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Name Operation 



[name] JDUMP 



[name] LBRET 
[name] LFCB 



[name] LITE 
[name] LOAD 



Iname) LOCK 
InaraeJ MODDTL 



[name] MRMOD 
[name] MTMOD 



[name] MVCOM 

[name] NOTE 

[name] {OPEN| 
OPENR) 

[name] ORMOD 



[name] PAGEIN 



Operands Use Page No. 

[,RDONLY=YES] 

[,RECFORM=FIXUNB|FIXBLK|BOTH] 

[,RPS=SVA] 

[,SEPASMB=YES] 

[,TYPEFLE=RANDOM|SEQNTL|RANSEQ] 

Produces a hexadecimal dump; teminates the main 

or subtask 5-11 

F1JNCT= {PUTCOMEGETCOM} . Permits <?Ojfefflantc2tiO!i behveen jobs 

AREA- {a<WressKr 1)) , tit job steps ia a jsartition , 5- 1 1: 

LENGTH»«{!eng;th|(t2)} 

{1|2|3} Returns control to IOCS after label-processing 4-14 

SYSxxXjphasename Loads the forms control buffer 5-12 

[,NULMSG] 

[,FORMS=xxxx] 

[,LPI=n] 

(filename 1(1)) Lights pocket lamps on 1419 or 1275 4-15 

[,light-switches|,(0)] 

{phasename|(S,address)|(l)} Loads specified phase; returns control to calling phase 5-13 

[,loadpoint I (S Joadpoint) | (0)] 

[,LIST= {listname|(S,listname)|(rl)] 

[,SYS=YES] 

[,DE=YES] 

[,TXT=NO] 

[,MFG= {area|(S,area)|(r2)} ] 

(naitte|(S,ttaaie)|^r)} Enques a. resource access request with 

i,FAlL= IRETURH jWAITCjWAJT] ] protection against disallowed 5-t4 

ADDR- {iiatBeiHS,namc iMfl)} Modifies a DTL (Defise The Lock) control blodk ,.,.. 5-15 

|,NAME- (n&me2l(S,aa»ie2)](r2>}l 

|,CONTROL"(E|S}l 

|,LOCKOPT={ii2}| 

l,KEEP-^NOSYES}| 

I.OWNER*' (TASK]PARTlTION}} 

[ADDRESS= (SINGLE IDUAL] ] Defines a logic module for a MICR or OCR file 3-45 

[,BUFFERS=nnn] 
[,SEPASMB=YES] 

[ASCII=YES] Defines a logic module for a magnetic tape file 3-51 

[,CKPTREC=YES] 

[,ERREXT=YES] 

[,ERROPT=YES] 

[,NOTEPNT= {YES|POINTS} ] 

[,RDONLY=YES] 

(,READ= {FORWARD|BACK} ] 

[,RECFORM={FIXUNB|FIXBLK|VARUNB| 

VARBLK|SPNBLK|SPNUNB!UNDEF}] 

to,length, {from|(0)} Modifies communication region 5-15 

{filename|(l)} Obtains identification for a physical record or logical block . . .4-15 

{filename 1 1 (rl)} Activates a file 4-15 

[,filename2|,(r2)],... 

[BLKFAC=YES] Defines a logic module for a 1287 or 1288 optical reader file . . 3-57 

[,CONTROL=YES] 

,DEVICE=(1287D|1287T} 

[,IOAREA2=YES] 

[,RECFORM= (FIXUNBIFIXBLKiUNDEF} ] 

[,SEPASMB=YES] 

[,WORKA=YES] 

{{listname|(l)}tbeginaddr,endaddr| Brings specified areas into real storage 5-16 

[,beginaddr.endaddr],...} 

[.ECB={ecbname;(0)}] 
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Name Operation 

[name] PDUMP 

[name] PFIX 

[name] PFREE 

[name] POINTR 

[name] POINTS 

[name] POINTW 

[name] POST 

[name] PRMOD 



[name] PRTOV 

[name] PTMOD 

[name] PUT 

[name] PUTR 

[name] RCB 

[name] RDLINE 

[name] READ 

[name] REALAD 

[name] RELEASE 

[name] RELPAG 

[name] RELSE 

[name] RESCN 

[name] RETURN 



Operands Use Page No. 

(,address|(rl)} , (address! |(r2)} Produces snapshot hexadecimal dump; 

[,MFG= (area|(S,area)|(r3)}] processing continues at next instruction 5-16 

({listnamej(l)] |beginaddr,endaddr Brings pages into real storage; fixes them 5-17 

[,beginaddr,endaddr] , . . .} 

{{listname|(l)) |beginaddr,endaddr Decrements a page's PFIX counter by 1 5-17 

[,beginaddr,endaddr] , . . .} 

{filename|(l)} Repositions a file to a specified record 4-16 

,(address|(0)} 

{filename|(l)} Repositions a file to its begining 4-16 

(filename|(l)} Repositions a file to a specified record 4-16 

,(address|(0)) 

{ecbname|(l)) Posts an ECB to a waiting task from the wait state 5-18 

[,SAVE=(savearea|(0))] 

[CONTROL=YES] Defines a logic module for a printer file 3-65 

[,CTLCHR=YES] 

[,DEVICE=xxxxx] 

[,ERROPT=YES] 

[,FUNC=xxxxxx] 

[,IOAREA2=YES] 

[,PRINTOV=YES] 

[,RDONLY=YES] 

[,RECFORM=xxxxxx] 

[,SEPASMB=YES] 

[,STLIST=YES] 

[,TRC=YES] 

[,WORK=YES] 

{filename|( 1)} ,(9112} Specifies printer action when carriage overflow occurs 4-17 

[,routinename|,(0)] 

[DEVICE=nnnn] Defines a logic module for a paper tape file 3-71 

[,RECFORM=xxxxxx] 
[,SCAN=YES] 
[SEPASMB=YES] 
[,TRANS=YES] 

(filenamel(l)} Moves (outputs) a logical record to I/O device 4-17 

[,worknamel,(0)] 
[,STLSP= (controlfieldl(r))] 
[,STLSK= (controlfieldl(r)} ] 

(filename|(l)} Sends message to operator's console, requiring a reply 4-18 

[,(worknamel|(0)} 
, (workname2|(2)} ] 

Generates a Resource Control Block 5-18 

(filename|( 1)} Reads a 1287 journal tape line in correction mode 4-18 

(filename|( 1)) Transfers data from an input file to an area in 

(,KEY|,ID|,MR| virtual storage 4-19 

,OR,(name|(r)}| 

,DR, (namel(r)|nn,nn} | 

,SQ,(area|(0))[,length|,(r)|,S]) 

(address|( 1)} Returns a real storage address corresponding to a 

virtual address 5-18 

(SYSnnn,SYSnnn,...) Releases programmer logical units 5-19 

[,savearea] 

((listname|(l)) |beginaddr,endaddr Releases specified storage areas 5-19 

[,beginaddr,endaddr],. . .} 

(filename|(l)) Skip the remaining records in a block 4-19 

(filename|( 1)) Rescans a field on an OCR document 4-19 

,(rl),(r2) 
,lnll[,n21 

(rl[,r2]) Restores registers, returns control to calling program 5-20 
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Name 


Operation 


Operands 


[name] 


RUNMODE 




[name] 


SAVE 


(r!r,r2]) 


[name] 


SDMOD 


[CONTROL=YES] 

[,ERREXT=YES] 

[,ERROPT=YES] 

[,FEOVD=YES] 

[,HOLD=YES] 

[,NOTEPNT= {POINTRWI YES) ] 

[,RDONLY=YES] 

[,RECFORM= (SPNUMBISPNBLK) 

[,RPS=SVA] 

[,SEPASMB=YES] 

[,TRUNCS=YES] 

[,UPDATE=YES] 


[name] 


SECTVAL 


[DDKR=(name|(0)}] 
[,DVCTYP=name2] 


[name] 


SEOV 


filename 


[name] 


SETDEV 


{filenamel(l)} 
, {phasename|(r)} 


[name] 


SETFL 


(filenamel(O)} 


[name] 


SETIME 


(timervalue|(l)} 
,[tecbname|(r)][,PREC] 


[name] 


SETL 


{filename|(r)} 
,{id-name|(r)| 
KEY|BOF|GKEY} 


[name] 


SETPFA 


[entryaddrl(O)] 


[name] 


SETT 


(timervalue|(l)} 


[name] 


STXIT 


{AB|lT|PC|OC|TT 

[,{rtnaddr|{0)} 
,{savearea|(i)} 
[,OPTION= {DUMP|NODUMP) ]] 


[name] 


TECB 




[name] 


TESTT 


[CANCEL] 


[name] 


TPIN 




[name] 


TPOUT 




[name] 


TRUNC 


{filename 1(1)} 


[name] 


TTIMER 


[CANCEL] 


InaJEnsj 


UNLOCK 


{{ntiame[(S,aain.c>fi(rj (jAtL} 


[name] 


VIRTAD 


{address|(l)} 


[name] 


WAIT 


{blocknamel(l)) 


[name] 


WAIT 


{ecbname|(l)} 


[name] 


WAITF 


{filenames 1)} [,filename2|,(r2)],... 



Use Page No. 

Returns mode information 5-20 

Saves registers in savearea 5-20 

Defines a logic module for a sequential DASD file 3-79 



[name] WAITM 



[name] WRITE 



[name] XECBTAB 



{ecbl,ecb2,...ilistname|(!)} 

{filename|(l)} 

{, {SQIUPDATE} , {area|(0)} [,length|,(r)]i 

,KEY|,ID|,AFTER[,EOF]| 

,NEWKEY|,RZERO} 

TYPE= {DEFINE|DELETE|CHECK| 
RESET|DELETALL} 

,XECB=xecbname 



Calculates the sector value for a CKD disk file record 4-20 

Forces end-of-volume for a system file on tape 4-20 

Changes 3886 format records 4-20 

Sets file-load mode in ISAM 4-21 

Sets interval to specified value 5-21 

Sets sequential retrieval mode in ISAM 4-21 

Makes or breaks a linkage to a page fault appendage routine . . 5-21 

Sets the task timer to the specified value 5-21 

Makes or breaks linkage from supervisor 

to your interrupt processing routine 5-22 

Generates a timer event control block 5-24 

Tests time elapsed from task timer set by SETT 5-25 

Deactivates partitions 5-25 

Reactivates partitions 5-25 

Writes a short block of records 4-21 

Tests time elapsed from interval timer set by SETIME 5-26 

Releases a feSOttr<* thatwa&ea<5ueaed 

by ^L0Clt«i4<*0 - - — .,.„., 



.5*^ 



Returns virtual address corresponding to real address 5-26 

PIOCS waits for an I/O operation to be 

completed before continuing 4-22 

Sets a task into a wait state until an ECB is posted 5-26 

LIOCS waits for an I/O operation to be 

completed before continuing 4-22 

Sets programs or tasks into wait state until ECBs 

are posted 5-27 

Transfers a record from virtual storage to an output file 4-22 



Defines or changes a cross-partition event control block 5-27 
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Name Operation Operands Use Page No. 

[,XECBADR= (xecbfield|(S,xecbfield)|(rl)} ] 
[,ACCESS= (XPOST|XWAIT) ] 
[,MFG= (area|(S,area)|(r2)} ] 

[name] XPOST XECB= {xecbname|(l)} Posts a specified XECB 5-28 

,POINTREG=(14) 

[name] XWAIT XECB= (xecbname|( 1)} Waits for a specified XECB to be posted 5-29 

,P0INTREG=(14) 
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Chapter 2: Macro Notation 



Macro Fields 

Macros, like assembler statements, have a name 
field, operation field, and operand field. Comments 
can also be included as in assembler statements, 
although certain macros require a comment to be 
preceeded by a comma if the macro is issued with- 
out an operand. These macros are; CANCEL, 

DETACH, FREEVIS, GETIME, GETVIS, TESTE, and 
TTIMER. 

The name field in a macro may contain a symbol- 
ic name. Some macros (for example, CCB, tecb, or 
DTFxx) require a name. 

The operation field must contain the mnemonic 
operation code of the macro. 

The operands in the operand field must be written 
in either positional, keyword, or mixed formats. 

Positional Operands 

In this format, the parameter values must be in the 
exact order shown in the individual macro discus- 
sion. Each operand, except the last, must be fol- 
lowed by a comma, and no embedded blanks are 
allowed. If an operand is to be omitted in the macro 
and following operands are included, a comma must 
be inserted to indicate the omission. No commas 
need to be included after the last operand. Column 
72 must contain a continuation punch (any non- 
blank character) if the operands fiU the operand 
field and overflow onto another line. 

For example, GET uses the positional format. A 
GET for a file named CDFILE using work as a work 
area is written: 

GET CDFILE, WORK 

Keyword Operands 

An operand written in keyword format has this 
form, for example: 

LABADDR=MYLABELS 

where labaddr is the keyword, mylabels is the 
specification, and labaddr=mylabels is the com- 
plete operand. 

The keyword operands in the macro may appear 
in any order, and any that are not required may be 
omitted. Different keyword operands may be writ- 
ten in the same statement, each followed by a com- 
ma except for the last operand of the macro. 



Mixed Format 

The operand Ust contains both positional and key- 
word operands. The keyword operands can be writ- 
ten in any order, but they must be written to the 
right of any positional operands in the macro. 

For additional information on coding macro 
statements, see OS/VS -DOS /VSE-VM/ 370 Assem- 
bler Language, as listed in the Preface. 

Notational Conventions 

The following conventions are used in this book to 
illustrate the format of macros: 

1 . Uppercase letters and punctuation marks 
(except as described in these conventions) rep- 
resent information that must be coded exactly 
as shown. 

2. Lowercase letters and terms represent informa- 
tion which you must supply. More specifically, 
an n indicates a decimal number, an r indicates 
a decimal register number, and an x indicates 
an alphameric character. 

3. Information contained within brackets [ ] repre- 
sents an optional parameter that can be includ- 
ed or omitted, depending on the requirements 
of the program. 

4. Stacked options contained within brackets rep- 
resent alternatives, one of which can be chosen 
for example: 



name 


A name-field symbol 


label 


in this assembly, or 


address 


an operand of an 




EXTRN statement. 




or * (the location 



counter). 

5. Stacked options contained within braces {} 
represent alternatives, one of which must be 
chosen. 

6. Items 4 and 5 above may also be shown be- 
tween brackets and braces, respectively, on one 
line, that is, unstacked. In that case, the options 
are separated by OR symbols (|). Examples of 
this notation are 

{phasename|(l)} [,entrypoint|,(0)] 

7. An ellipsis (a series of three periods) indicates 
that a variable number of items may be includ- 
ed. 

8. filename Example of a symbol appearing in 

the name field of a DTF macro. 
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9. n Self-defining value, such as 3, 

X'04',(15),B'010'. 

10. length Absolute expression, as defined in 

OS/ VS-DOS/ VSE- VM/370 As- 
sembler Language, as listed in the 
Preface. 

11. {A|B|C} Underlined elements represent an 

assumeu VaiuC in tue event an ope- 
rand is omitted. 

12. (r) Ordinary register notation. Any 

register except or 1 to be specified 
in parentheses. 

13. (0)1(1) Special register notation (ordinary 

register notation can be used). 

Register Notation 

Certain operands can be specified in either of two 
ways: 

1 . You may specify the operand directly which 
results in code that, for example, cannot be exe- 
cuted in the SVA because it is not reentrant. 

2. You may load the address of the value into a 
register before issuing the macro. This way the 
generated code is reentrant and may be execut- 
ed in the sva. When using register notation, 
the register should contain only the specific 
address and high order bits should be set to 0. 

When the macro is assembled, instructions are 
generated to pass the information contained in the 
specified register to IOCS or to the supervisor. For 
example, if an operand is written as (8), and if the 
corresponding parameter is to be passed to the su- 
pervisor in register 0, the macro expansion contains 
the instruction LR 0,8. This is an example of ordi- 
nary register notation. 

You can save both storage and execution time by 
using what is known as special register notation. In 
this method, the operand is shown in the format 
description of the macro as either (0) or (1), for ex- 
ample. This notation is special because the use of 
registers and 1 is allowed only for the indicated 
purpose. 

If special register notation is indicated by (0) or 
(1) in a macro format description and you use ordi- 
nary register notation, the macro expansion will 
contain an extra LR instruction. 

The format description for each macro shows 
whether special register notation can be used, and 
for which operands. The following example indi- 
cates that the filename operand can be written as (1) 
and the workname operand as (0): 



GET (filename|(l)}[workname|,(0)] 

If either of these special register notations is used, 
your program must load the designated parameter 
register before executing the macro expansion. Or- 
dinary register notation can also be used. 

Operands in (s, address) Notation 

Certain system control macros (for instance, 
ATTACH, GENIORB, GENL, LOAD) allow three nota- 
tions for an operand: 

1 . Register notation, as described in the preceding 
paragraph. 

2. Notation as a relocatable expression which, in 
the macro expansion, results in an A-type ad- 
dress constant. 

3. Notation in the form (s,address). In the macro 
expansion, an expUcit address (that is: an as- 
sembler instruction address in base- 
displacement form) is generated. Address can 
be specified either as a relocatable expression 
—for example: (s.RELOC), or as two absolute 
expressions, the first of which represents the 
displacement and the second, the base register 
—for example: (s,5 12(12)). 

You should consider using this notation if your 
program is to be reenterable. In a reenterable pro- 
gram, macro operands often refer to fields in dy- 
namic storage. The (s,address) format offers an 
alternative to register notation: if two or more of 
such operands have to be provided for one macro, 
there is no need for loading addresses into that many 
registers. 

Declarative Macro Statements 

The operands of the dtfxx and the logic module 
generation macros are written in assembler format 
statements. The first statement is the header and the 
continuations following are the detail statements. 
The header contains: 

• The symbolic name of the file in the name field. 
In a DTP, the symbolic file name may have as 
many as seven characters. The file name may 
also be required on standard label job control 
statements and in certain macros as operands; it 
must be the same as that used in the DTP head- 
er. For a logic module, the name may not be 
required. 

• The mnemonic operation code of the macro in 
the operation field. 

• Keyword operands in the operand field, as re- 
quired. 

• A continuation character in column 72, if re- 
quired. 
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Note: Avoid using IJ as the first two letters when defining sym- 
bols as they may conflict with IOCS symbols beginning with IJ. 
Avoid symbols that are identical to a filename plus a single char- 
acter suffix because IOCS generates symbols by concatenating 
the filename with an additional character. For the filename 
RECIN, for example, IOCS generates the symbols RECINS, 
RECINI, etc. 

The details follow the header and may be ar- 
ranged in any convenient order. Each continuation 
line must begin in column 16. If more than one ope- 



rand is written on a detail line, they must be separat- 
ed by a comma only. Except for the final detail line, 
there must be a comma immediately following each 
operand and have a continuation character in col- 
umn 72. You may include a comment on a header 
or a detail line if there is room between a space fol- 
lowing the last operand on a hne and column 72. 
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Chapter 3: Declarative Macros 



DTFCD Macro 

This macro defines a file for a card reader. 



Applies to 








Input 


Output 


Combined 




X 


X 


X 


M 


DEVADDR=SYSxxx 


Symbolic unit for reader-punch used for this file 


X 


X 


X 


M 


10AREA1 =xxxxxxxx 


Name of first I/O area, or separate input area if 
TYPEFLE=CMBND and I0AREA2 are specified. 


X 


X 







ASOCFLE=xxxxxxx 


Name for FUNC=RP, RW, RPW, PW 


X 


X 


X 





BLKSIZE=nnn 


Length of one 1/0 area, in bytes. If omitted, 160 is assumed 
for a column binary on the 2560,3504,3505. or 3525; 96 is 
assumed for the 2596 or 5424/5425, otherwise 80 is as- 
sumed. 


X 


X 


X 





CONTROL=YES 


CNTRL macro used for this file. Omit CTLCHR for this file. 
Does not apply to 2501 . 




X 







CRDERR= RETRY 


RETRY if punching error is detected. Applies to 2520 and 
2540 only. 




X 







CTLCHR=xxx 


(YES or ASA). Data records have control character. YES for 
S/370 character set; ASA for American National Standards 
Institute character set. Omit if TYPEFLE=CMBND. Omit CON- 
TROL for this file. 


X 


X 


X 


O 


DEVlCE=nnnn 


(1442, 2501, 2520, 2540, 2560P, 2560S, 2596, 3504, 3505, 
3525, 5425P, or 5425S). If omitted, 2540 is assumed. Speci- 
fy 5425P/S for 5424/5425(P/S). 


X 




X 





EOFADDR = xxxxxxxx 


Name of your end-of-file routine. 


X 


X 







ERROPT=xxxxxx 


IGNORE, SKIP, or name. Applies to 2560, 3504, 3505, 3525 
and 5424/5425 only. 


X 


X 







FUNC=xxx 


R, P, 1, RP, RW, RPW, PW. Applies to 2560, 3525, and 
5424/5425 only. 


X 


X 


X 





I0AREA2 =xxxxxxx 


Name of second I/O area, or separate output area if 
TYPEFLE=CMBND. Not allowed if FUNC=RP. RW, RPW, or 
PW. Not allowed for output file if ERROPT=IGNORE. 


X 


X 




. 


IOREG=(nn) 


Register number, if two I/O areas used and GET or PUT does 
not specify a work area. Omit WORKA. 


X 


X 







MODE=xx 


(E or C) for 2560. (E, C, 0, R. EO, ER, CO, CR) for 3504 and 
3505. (E, C, R, ER, CR) for 3535. If omitted, E is assumed. 


X 


X 


X 





MODNAME=xxx/xxxx 


Name of CDMOD logic module for this DTF. If omitted, IOCS 
generates standard name. 



M= Mandatory 
0=Optional 

Figure 3-L DTFCD macro operands (Part 1 of 2). 
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Applies to 








Input 


Output 


Combined 








X 





OUBLKSZ=nn 


Length of IOAREA2 if TYPEFLE=CMBND. If OUBLKSZ omit- 
ted, length specified by BLKSIZE is assumed for I0AREA2. 


X 


X 


X 





RDONLY=YES 


Generates a read-only module. Requires a module save area 
for each task using the module. 


X 


X 


X 





RECFORM=xxxxxx 


(FIXUNB, UNDEF, or VARUNB). If omitted, FIXUNB is as- 
sumed. Input or combined files always FIXUNB. 




X 







RECSIZE=(nn) 


Register number if RECFORM=UNDEF. General registers 
2-1 2, written in parentheses. 


X 


X 


X 





SEPASMB=YES 


DTFCD is to be assembled separately. 


X 


X 







SSELECT=n 


(1 or 2) for 1 442, 2520, 2596, 3504, or 3525. (1 , 2, or 3) for 
2540. (1 , 2, 3, 4, or 5) for 2560. (1 , 2, 3, or 4) for 
5424/5425. Stacker-select character. 


X 


X 


X 





TYPEFLE=xxxxxx 


(INPUT, OUTPUT, or GMBND) If omitted INPUT assumed. 
CMBND may be specified for 1442N1 , 2520B1 , or 2540 
punch-feed-read only. 


X 


X 


X 





WORKA=YES 


GET or PUT specifies work area. Omit lOREG. Not allowed for 
output file if ERROPT=IGNORE. 



M = Mandatory 
0= Optional 

Figure 3-1. DTFCD macro operands (Part 2 of 2). 



Code in FUNC= operand 


filename specification in ASOCFLE = operand of 


read DTFCD 


punch DTFCD 


print DTFPR 


FUNC=PW 




filename of print DTFPR 


filename of punch DTFGD 


FUNC=RP 


filename of punch 
DTFGD 


filename of read DTFGD 




FUNC=RPW 


filename of punch 
DTFGD 


filename of print DTFPR 


filename of read DTFGD 


FUNC=RW 


filename of print DTFPR 




filename of read DTFGD 


Examples: 

1 . If FUNG = PW is specified , 

a. specify the filename of the print DTFPR in the ASOCFLE operand of the punch DTFGD and 

b. Specify the filename of the punch DTFCD in the ASOGFLE operand of the print DTFPR. 

2. If FUNG=RPW is specified, 

a. specify the filename of the punch DTFGD in the ASOGFLE operand of the read DTFGD, and 

b. specify the filename of the print DTFPR in the ASOGFLE operand of the punch DTFGD, and 

c. specify the filename of the read DTFGD in the ASOGFLE operand of the print DTFPR. 



Figure 3-2. ASOCFLE operand usage with print associated files. 

ASOCFLE=filenaine: This operand is used to- 
gether with the FUNC operand to define associated 
files for the 2560, 3525, or 5424/5425. (For a de- 
scription of associated files see the DOS/ VSE Ma- 
cro User's Guide , as listed in the Preface.) ASOCFLE 
specifies the filename of associated read, punch, or 
print files, and enables macro sequence checking by 



the logic module of each associated file. One filen- 
ame is required per DTP for associated files. 

BLKSIZE=n: Enter the length of the I/O area 
(lOAREAl). If the record format is variable or unde- 
fined, enter the length of the largest record. If the 
operand FUNC=I is specified for the 2560 or 3525, 
the length specified for BLKSIZE must be 80 data 
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bytes if CTLCHR=YES or if as a is not specified, or 81 
if CTLCHR=YES or if ASA is Specified. 

CONTROL=YES: This operand is specified if a 
CNTRL macro is to be issued for a file. If this ope- 
rand is specified, CTLCHR must be omitted. The 
CNTRL macro cannot be used for an input file with 
two I/O areas (that is, when the I0AREA2 operand is 
specified). 

This operand must not be specified for an input 
file used in association with a punch file (when the 
operand func=rp or rpw is specified) on the 2560, 
3525, or 5424/5425; in this case, however, this ope- 
rand can be specified in the dtfcd for the associat- 
ed punch file. 

CRDERR=RETRY: This operand applies to card 
output on the 2520 or 2540. It specifies the opera- 
tion to be performed if an error is detected. From 
this specification, IOCS generates a retry routine and 
a save area for the card punch record. 

If a punching error occurs, it is usually ignored 
and operation continues. The error card is stacked 
in stacker Pi (punch), while correct cards are stacked 
in the stacker you select. If the crderr=retry 
operand is included and an error condition occurs, 
IOCS also notifies the operator and then enters the 
wait state. The operator can either terminate the 
job, ignore the error, or instruct IOCS to repunch the 
card. 

CTLCHR= {ASA| YES) : This operand is required 
if first-character control is to be used on an output 
file. ASA denotes the American National Standards 
Institute, Inc. character set. YES denotes the EBCDIC 
character set. Appendix A of DOS/ VSE Macro 
User's Guide contains a complete list of codes. This 
entry does not apply to combined files. If this ope- 
rand is specified, CONTROL must be omitted. 

DEVADDR= {SYSIPT|SYSPCH|SYSRDR| 

SYSnnn): 
This operand specifies the symbolic unit to be asso- 
ciated with a file. The symbolic unit represents an 
actual I/O device address and is used in the ASSGN 
job control statement to assign the actual I/O device 
address to the file. 

SYSIPT, SYSPCH, or SYSRDR must not be specified: 

• for the 2596 

• for the 3881 

• for 1442, 2520, or 2540 combined files 

(TYPEFLE=CMBND) 

• for 2560, 3525, or 5424/5425 associated files 

(FUNC=RP, RW, RPW, or PW) 



• if the operand FUNC=i is specified 

• if the MODE operand is specified with the c, o, 
or R parameters. 

DEVICE^ {2540|1442|2501|2520|2560P| 
2560S|2596|3504|3505|3525| 
5425P|5425S|3881}: 
This operand specifies the I/O device associated with 
a file. The "p" and "s" included with the "2560" 
and "5425" parameters specify primary or second- 
ary input hoppers. Specify 5425P/S for 5424P/S. 

Note: Modifications to the double buffering concept in LIOCS 
provide for increased throughput for SYSIPT or SYSRDR files 
on 2501 card readers attached to a S/370-1 15-2, S/370- 125-0, or 
S/370-125-2. If you specify DEVICE=2501 together with 
DEVADDR=SYSIPT1SYSRDR and I0AREA2=name, this will 
lead to the generation of a second CCB with its CCW pointing to 
the second I/O area. 

EOFADDR=name: This entry must be included 
for input and combined files and specifies the sym- 
bolic name of your end-of-file routine. IOCS auto- 
matically branches to this routine on an end-of-file 
condition. In your routine you can perform any 
operations required for the end of the file (you gen- 
erally issue a CLOSE instruction for the file). 

IOCS detects end-of-file conditions in the card 
reader by recognizing the characters /* punched in 
card columns 1 and 2 (column 3 must be blank). If 
the system logical units SYSIPT and SYSRDR are as- 
signed to a 5424/5425, iocs requires that the /* 
card, indicating end-of-file, be followed by a blank 
card. An error condition results if cards are allowed 
to run out without a /* trailer card (and without a 
/& card to indicate end-of-job). 

ERROPT= (IGNORE|SKIP|name} : This ope- 
rand specifies the error exit option used for an input 
or output file on a 2560, 3504, 3505, 3525, or 
5424/5425. Either IGNORE, skip, or the symbolic 
name of an error routine can be specified for input 
files. Only IGNORE can be specified for output files. 
This operand must be omitted when using 2560 or 
5424/5425 associated output files. The functions of 
these parameters are described below. 

IGNORE indicates that the error is to be ignored. 
The address of the record in error is put in register 1 
and made available for processing. For output files, 
byte 3, bit 3 of the CCB is also set on (see Figure 4-2); 
you can check this bit and take the appropriate ac- 
tion to recover from the error. Only one I/O area 
and no work area is permitted for output files. 
When IGNORE is specified for an input file associat- 
ed with a punch file (func=RP or RPW) and an error 
occurs, a PUT for the card in error must nevertheless 
be given for the punch file. 
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SKIP indicates that the record in error is not to be 
made available for processing. The next card is read 
and processing continues. 

If name is specified, iocs branches to your rou- 
tine when an error occurs, where you may perform 
whatever actions you desire. Register 1 contains the 
address of the record in error, and register 14 con- 
tains the return address, get macros must not be 
issued in the error routine for cards in the same de- 
vice (or in the same card path for the 2560 or 
5424/5425). If the file is an associated file, PUT mac- 
ros must not be issued in the error routine for cards 
in the same device (for the 2560 or 5424/ 5425 this 
applies to cards in either card path). If any other 
IOCS macros are issued in the routine, register 14 
must be saved. If the operand rdonly=yes is spec- 
ified, register 13 must also be saved. At the end of 
your routine, return to IOCS by branching to the 
address in register 14. If the input file is associated 
with an output file (FUNC=RP, RPW, or RW), no 
punching or printing must be done for the card in 
error. IOCS continues processing by reading the next 
card. 

Note: When ERROPT is specified for an input file and an error 
occurs, there is a danger that the /* end-of-file card may be lost. 
This is because IOCS, after taking the action for the card in error 
specified by the ERROPT operand, returns to normal processing 
by reading the next card which is assumed to be a data card. If 
this card is in fact an end-of-file card, the end-of-file condition 
cannot be recognized. 

FUNC={R|P|I|RP|RW|RPW|PW}: This operand 
specifies the type of file to be processed by the 2560, 
3525, or 5424/5425. R indicates read, P indicates 
punch, and w indicates print. 

When FUNC=I is specified, the file will be both 
punched and interpreted; no associated file is neces- 
sary' to achieve this. The information printed will be 
the same as the information punched, in contrast to 
FUNC=PW, where any relation between the informa- 
tion printed and the information punched is deter- 
mined by your program. When FUNC=I is specified 
the file can have only one I/O area. 

RP, RW, RPW, and PW are used, together with the 
ASOCFLE operand, to specify associated files; when 
one of these parameters is specified for one file, it 
must also be specified for the associated file(s). Each 
of the associated files can have only one I/O area. 

IOAREAl=name This operand specifies the name 
of the input or output area used for this file. 

If issued for a combined file, this operand speci- 
fies the input area. If IOAREA2 is not specified, the 
area specified in this operand is used for both input 
and output. 



IOAREA2=name: This operand specifies the name 
of a second I/O area. If the file is a combined file 
and the operand is specified, the designated area is 
an output area. 

If this operand is specified for the 3881, the 
lOREG operand must also be specified. 

This operand must not be specified if, for the 
FUNC operand, any of the parameters I, RP, RPW, RW, 
or PW is specified or if, for an output file, 
ERROPT=lGNORE is specified. 

IOREG=(r): If work areas are not used but two 
input or output areas are, this operand specifies the 
register (any of 2 through 12) in which IOCS puts the 
address of the record. For output files, IOCS puts the 
address where the user can build a record. This ope- 
rand cannot be used for combined files. 

This operand must be specified for the 3881 if the 
IOAREA2 operand is specified. 

MODE= {E|C|0|R|EO|ER|CO|CR) : This ope- 
rand specifies the mode used to process an input or 
output file for a 2560, 3504, 3505, or 3525. E indi- 
cates normal EBCDIC mode; c indicates column bi- 
nary mode; o indicates optical mark read (OMR) 
mode; R indicates read column eliminate mode. E is 
also assumed if only o or R is specified. 

For the 2560, only E and c are valid entries. 

Valid entries for the 3504 and 3505 are E, c, o, R, 
EO, ER, CO, and CR. Valid entries for the 3525 are E, 
C, R, ER, and CR. If o or R is specified (with or with- 
out E or c), a format descriptor card defining the 
card columns to be read, or eliminated, must be 
provided. See OMR considerations in the DOS/VSE 
Macro User's Guide, as listed in the Preface, for in- 
structions on how to write this card as well as on 
how to code and process OMR data. 

Only E is valid for SYSIPT, SYSPCH, or SYSRDR. o 
and R (with or without E or c) cannot be specified 
for output files. E is assumed if the mode operand is 
omitted. 

MODNAME=name: This operand is used to speci- 
fy the name of the logic module that will be used 
with the DTF table to process the file. If the logic 
module is assembled with the program, MODNAME 
must specify the same name as the CDMOD macro. 

If this operand is omitted, standard names are 
generated for calling the logic module. If two DTF 
macros call for different functions that can be han- 
dled by a single module, only one module is called. 
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OUBLKSZ=n: This operand is used in conjunction 
with I0AREA2, but only for a combined file. Enter 
the maximum number of characters to be transfer- 
red at one time. If this entry is not included and 
IOAREA2 is specified, the same length as defined by 
BLKSIZE is assumed. 

RDONLY=YES: This operand is specified if the 
DTP is used with a read-only module. Each time a 
read-only module is entered, register 13 must con- 
tain the address of a 72-byte doubleword-aligned 
save area. (In the case of double buffering support 
for the 2501 Card Reader, the save area must be 76 
bytes to include the second CCB generated.) Each 
task should have its own uniquely defined save area. 
Each time an imperative macro (except open or 
OPENR) is issued, register 13 must contain the ad- 
dress of the save area associated with that task. The 
fact that the save areas are unique for each task 
makes the module reentrant (that is, capable of be- 
ing used concurrently by several tasks). 

If an ERROPT routine issues I/O macros using the 
same read-only module that caused control to pass 
to the error routine, your program must provide 
another save area. One save area is used for the 
normal I/O operations, and the second for I/O opera- 
tions in the erropt routine. Before returning to the 
module that entered the ERROPT routine, register 13 
must contain the save area address originally speci- 
fied for the task. 

If this operand is omitted, the module generated 
is not reenterable, and no save area is required. 

RECFORM= {FIXUNB|VARUNB|UNDEF} : 
This operand specifies the record format of the file: 
fixed length, variable length, or undefined. If the 
record format is fixed unblocked (FIXUNB,) this ope- 
rand may be omitted. This operand must specify 
FIXUNB if you also specified one of the following: 

TYPEFLE=INPUT 
TYPEFLE=CMBND, 
FUNC=I 
DEVICE=3881. 

RECSIZE=(r) For undefined records, this operand 
specifies the register (one of 2 through 12) that con- 
tains the length of the output record. You must load 
the length of each record into the specified register 
before you issue the PUT macro for the record. 



SEPASMB=YES: Include this operand only if the 
DTFCD is assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and defines the filename as an 
ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the dtf is being 
assembled with the problem program and no 
CATALR card is punched. 

SSELECT=n: This operand specifies the valid 
stacker-select character for a file. If this entry is not 
specified, cards are selected into NR (normal read) or 
NP (normal punch) stackers. For the 5424/5425, 
cards from hopper 1 are placed in stacker 1 and 
cards from hopper 2 are placed in stacker 5 (or 4). 

This operand must not be specified for combined 
files, for files on the 3881, for 2560, 3525, or 
5424/5425 read files associated with punch files 
(FUNC=RP or FUNC=RPW); in this case the 
SSELECT=n operand may be specified for the associ- 
ated output file. For further information, see 
"CNTRL Macro." 

Note: When this operand is used with a device other than a 1442 
or 2596, the program ignores CONTROL=YES with input files. 

TYPEFLE= {INPUT I OUTPUT I CMBND): This 
operand specifies whether a file is input, output, or 
combined. A combined file can be specified for a 
1442 or 2520 or for a 2540 with the punch-feed-read 
feature. typefle=cmbnd is applicable if both gets 
and PUTS are issued for the same card file. 

Only TYPEFLE=INPUT Can be specified for the 
3881. If OUTPUT or CMBND is specified, the DTF 
defaults to DEVICE=2540 and a non-executable 
CDMOD logic module is produced. The mnote 
"Improper device. 2540 assumed." is then printed at 
assembly time. If the operand is omitted, INPUT is 
assumed. 

WORKA=YES: If I/O records are processed in 
work areas instead of in the I/O areas, specify this 
operand. You must set up the work area in storage. 
The address of the work area, or a general-purpose 
register which contains the address, must be speci- 
fied in each GET and PUT macro. 

If ERROPT=lGNORE is Specified for an output file 
or if DEVICE=3881, woRKA=YES must not be speci- 
fied. 
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CDMOD Macro 

Listed here are the operands you can specify for 
CDMOD. The first card contains CDMOD in the oper- 
ation field and may contain a module name in the 
name field. 

CONTROL^YES: Include this operand if the 
CNTRL macro is used with the module and its associ- 
ated DTPS. The module also processes files for which 
the CNTRL macro is not used. 

If this operand is specified, the CTLCHR operand 
must not be specified. This operand cannot be speci- 
fied if IOAREA2 is used for an input file. 

This operand must not be specified for an input 
file used in association with a punch file (when the 
operand FUNC=RP or RPW is specified) on the 2560, 
3525, or 5424/5425; in this case, however, this ope- 
rand can be specified in the dtfcd and CDMOD for 
the associated punch file. 

CRDERR=RETRY: Include this operand if error 
retry routines for the 2540 and 2520 punch- 
equipment check are included in the module. 
Whenever this operand is specified, any DTF used 
with the module must also specify the same operand. 
This operand does not apply to an input or a com- 
bined file. 

CTLCHR=: {ASA| YES) : Include this operand if 
first character stacker select control is used. Any 
DTP to be used with this module must have the same 
operand. If CTLCHR is included, control must not 
be specified. This operand does not apply to a com- 
bined file or to an input file. 

DEVICE= (2540 1 144212501 !2520|2560P| 
2560SJ2596i3504|3505'|3525| 
5425Pi5425Si3881}: 
Include this operand to specify the I/O device used 
by the module. The "P" and "s" included with the 
"2560" and "5425" parameters specify primary or 
secondary input hoppers; regardless of which is 
specified, however, the module generated will han- 
dle DTPS specifying either hopper. Specify 5425 P/S 
for 5424P/S. 

Any DTP to be used with this module must have 
the same operand (except as just noted concerning 
the 'P' and 's' specification for the 2560 or 5425). 

FUNC= (R|P|I|RP|RW|RPW|PW} This operand 
specifies the type of file to be processed by the 2560, 
3525, or 5424/5425. Any DTP used with the module 
must have the same operand. R indicates read, P 
indicates punch, and w indicates print. 



When FUNC=I is specified, the file will be both 
punched and interpreted; no associated file is neces- 
sary to achieve this. 

RP, RW, RPW, and PW specify associated files; 
when one of these parameters is specified for one 
file, it must also be specified for the associated 
file(s). Associated files can have only one I/O area 
each. 

IOAREA2=YES: Include this operand if a second 
I/O area is used. Any DTP used with the module 
must also include the IOAREA2 operand. This ope- 
rand is not required for combined files. This ope- 
rand is not valid for associated files. 

RDONLY=YES: This operand causes a read-only 
module to be generated. Whenever this operand is 
specified, any DTP used with the module must have 
the same operand. 

RECFORM= (FIXUNB I VARUNBIUNDEF) : 
This operand specifies the record format: fixed- 
length, variable-length, or undefined. Any DTP used 
with the module must have the same operand. If 

TYPEFLE=INPUT, TYPEPLE=CMBND, or PUNC=I, this 

Operand must be PIXUNB. For the 3881, only 
RECP0RM=PIXUNB is valid. If this operand is omit- 
ted for the 3881, IOCS assumes RECFORM=FixuNB. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and defines the module name as an ENTRY 
point in the assembly. If the operand is omitted, the 
assembler assumes that the module is being assem- 
bled with the DTP and the problem program and no 
CATALR card is punched. 

TYPEFLE= (INPUT |OUTPUT|CMBND) : This 
operand generates a module for either an input, 
output, or combined file. Any DTP used with the 
module must have the same operand. For the 3881, 
only TYPEPLE=INPUT is valid. If the operand is 
omitted, input is assumed. 

WORKA=YES: This operand must be included if 
records are to be processed in work areas instead of 
in I/O areas. Any DTP used with the module must 
have the same operand. This operand is not valid 
for the 3881. 

Standard CDMOD Names 

Each name begins with a 3-character prefix (uc) 
and continues with a 5 -character field corresponding 
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to the options permitted in the generation of the 
module. 

CDMOD name = IJCabcde 

a = F RECFORM=FIXUNB (always for INPUT, CMBND, 
or FUNC=I files) 

= V RECFORM=VARUNB 

= U RECFORM=UNDEF 

b = A CTLCHR=ASA (not specified if CMBND) 

= Y CTLCHR=YES 

= C CONTROL=YES 

= Z CTLCHR or CONTROL not specified 

c = B RDONLY=YES and TYPEFLE=CMBND 

= C TYPEFLE=CMBND 

= H RDONLY=YES and TYPEFLE=INPUT 

= I TYPEFLE=INPUT 

= N RDONLY=YES and TYPEFLE=OUTPUT 

= O TYPEFLE=OUTPUT 

d = Z WORKA and IOAREA2 not specified 
= W WORKA=YES 
= I I0AREA2=YES 
= B WORKA and IOAREA2 
= Z WORKA=YES not specified (CMBND file only) 

e = DEYICE=2540,3881 
= 1 DEVICE= 1442, 2596 
= 2 DEVICE=2520 
= 3 DEVICE=2501 
= 4 DEVICE=2540 and CRDER 
= 5 DEVICE=2520 and CRDERR 
= 6 DEVICE=3505 or 3504 
= 7 DEVICE=3525 and FUNC=R/P or omitted 
= 8 DEVICE=2560 and FUNC=R/P or omitted 
= 9 DEVICE=5425 and FUNC=R/P or omitted 
= A DEVICE=3525 and FUNC=RP 
= B DEVICE=3525 and FUNC=RW 
= C DEVICE=3525 and FUNC=PW 
= D DEVICE=3525 and FUNC=I 
= E DEVICE=3525 and FUNC=RPW 
= F DEYICE=2560 and FUNC=RP 



G DEVICE= 
H DEVICE= 
I DEVICE= 
J DEVICE= 
K DEYICE= 
L DEVICE= 
M DEVICE= 
N DEYICE= 
O DEVICE= 



2560 and 
2560 and 
2560 and 
2560 and 
5425 and 
^5425 and 
^5425 and 
6425 and 
6425 and 



FUNC=RW 

FUNC=PW 

FUNC=I 

FUNC=RPW 

FUNC=RP 

FUNC=RW 

FUNC=PW 

FUNC=I 

FUNC=RPW 



Subset/Superset CDMOD Names 

Figure 3-3 shows the subsetting and supersetting 
allowed for CDMOD names. All but one of the par- 
ameters are exclusive (that is, do not allow superset- 
ting). A module name specifying C (control) in 
the b location is a superset of a module name speci- 
fying z (no control or ctlchr). A module with 
the name IJCFCIWO is a superset of a module with 
the name IJCFZIWO. 



* * 
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+ Subsetting/supersetting 


permitted. 


* No subsetting/supersetting permitted. | 



Figure 3-3. Subsetting and supersetting of CDMOD names. 
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DTFCN Macro 

DTFCN defines an input or output file that is processed ona3210or3215 console printer-keyboard, or a 
display operator console, dtfcn provides GET/PUT logic as well as PUTR logic for a file. 



M 


DEVADDR = SYSxxx 


Symbolic unit for the console used for ttiis file. 


M 


iOAREM =xxxxxxxx 


Name of I/O area. 





BLKSiZE = nnn 


Lengtti in bytes of I/O area (for PUTR macro usage, length of output part of I/O 
area). If RECFORM=UNDEF, max. is 256. If omitted, 80 is assumed. 





INPSIZE = nnn 


Length in bytes for input part of I/O area for PUTR macro usage. 


O 


MODNAME = xxxxxxx 


Logic module name for this DTF. If omitted, IOCS generates a standard name. The 
logic module is generated as part of the DTF. 





RECFORM = xxxxxx 


(FIXUNB or UNDEF). If omitted, FIXUNB is assumed. 


O 


RFCSiZE=(nn) 


Register number if nECFORfvi = UNDEF. General registers 2-12, written in parenthes- 
es. 





TYPEFLE = xxxxxx 


(INPUT, OUTPUT, or CMBND). INPUT processes both input and output. CMBND 
must be specified for PUTR macro usage. If omitted, INPUT is assumed. 


O 


WORKA=YES 


GET or PUT specifies work area. 



M = Mandatory 
0= Optional 

Figure 3-4. DTFCN macro operands. 

BLKSIZE=n: This operand specifies the length of 
the I/O area; if the PUTR macro is used 
(TYPEFLE=CMBND is Specified), this operand speci- 
fies the length of the output part of the I/O area. For 
the undefined record format, BLKSIZE must be as 
large as the largest record to be processed. The 
length must not exceed 256 characters. 

If the console buffering option is specified at sys- 
tem generation time and the device is assigned to 
SYSLOG, physical IOCS can increase throughput for 
each actual output record not exceeding 80 charac- 
ters. This increase in throughput results from start- 
ing the output I/O command and returning to the 
program before output completion. Regardless of 
whether or not output records are buffered (queued 
on an I/O completion basis), they are always printed 
or displayed in a first-in-first-out (FIFO) order. 

DEVADDR= (SYSLOG I SYSnnn} : This operand 
specifies the symbolic unit associated with the file. 
In a multiprogramming environment, 
DEVADDR=SYSLOG must be specified to obtain par- 
tition identification prefixes (BG, Fi, F2, F3, and F4) 
for message identification. 

DEVADDR=SYSLOG must be specified if your 
DTFCN macro includes TYPEFLE=CMBND. 

INPSIZE=n: This operand specifies the length of 
the input part of the I/O area for putr macro usage. 

IOAREAl=name; This operand specifies the name 
of the I/O area used by the file. For PUTR macro 
usage, the first part of the I/O area is used for output. 



and the second part is used for input. The lengths of 
these parts are specified by the BLKSIZE and iNPSiZE 
operands respectively. The I/O area is not cleared 
before or after a message is printed, or when a mes- 
sage is canceled and reentered on the console. 

MODNAME=name: This operand specifies the 
name of the logic module generated by this DTFCN 
macro. If this entry is omitted, standard module 
names are generated for the logic module. 

A module name must be given when two phases 
(each containing a DTFCN macro) are hnk-edited 
into the same program. Under such conditions, 
omission of this operand results in unresolved ad- 
dress constants. 

RECFORM= (FIXUNB IUNDEF) : This operand 
specifies the record format of the file: fixed length or 
undefined. FixUNB must be specified if 
TYPEFLE=CMBND is Specified. FIXUNB is assumed if 
the RECFORM operand is omitted. 

RECSIZE=(r): For undefined records, this ope- 
rand is required for output files and is optional for 
input files. It specifies a general register (2 to 12) 
that contains the length of the record. On output, 
you must load the length of each record into the 
specified register before you issue a PUT macro. If 
specified for input files, IOCS provides the length of 
the record transferred to storage. 
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TYPEFLE= {INPUT|OUTPUT|CMBND) : This sure that messages requiring operator action are not 

operand specifies a file as input, output, or com- deleted from the console. When cmbnd is specified, 

bined. If input is specified, code is generated for devaddr=syslog must also be specified. 

both input and output files. If OUTPUT is specified, 

code is provided for output files only. mrkn^A vuo -ru- a ■ a- * ^u . 

.1- -r- AC <.u ^x. ^ WORKA= YES: This Operand indicates that a 

CMBND must be specified ifyou use the PUTR , . , vu ^u ^-i a ^r.-^ „Tr^ 

■ r- ^u ^ \i- u ^ A work area IS used with the file. A GET or PUT macro 

macro. CMBND specifies that coding be generated , , ^ , 

^ , ,, . ^ J ^ ^ r-i • jjv J- • moves the record to or from the work area. A PUTR 

for both input and output files; in addition, coding is , , ^ , , , 

^ J ^ „ f *u ^TTrr^T^ ^ 4. macro moves the record from and to the work area, 

generated to allow usage of the PUTR macro to en- 
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DTFDA Macro 

The DTFDA macro defines a file for Direct Access Method (DAM) processing. 



Applies to 








Input 


Output 




X 


X 


M 


BLKSIZE=nnnn 


Length of one I/O area, in bytes 


X 


X 


M 


DEVICE = nnnn 


(231 1 , 2314, 3330, 3340, 3350). If omitted, 231 1 is assumed. Specify any 
device for a 3330-1 1 or 3350. 


X 


X 


M 


ERRBYTE=xxxxxxxx 


Name of 2-byte field for error/status codes supplied by IOCS 


X 


X 


M 


I0AREA1 =xxxxxxxx 


Name of I/O area 


X 


X 


M 


SEEKADR=xxxxxxxx 


Name of tracl^-reference field 


X 


X 


M 


TYPEFLE = xxxxxx 


(INPUT or OUTPUT) 






r\ 


AFTER -YES 


WRITE filename, AFTER or WRITE filename, RZERO macro is used for this 
file 


X 


X 





CONTROL=YES 


CNTRL macro is used for this file 


X 


X 


o 


DEVADDR=SYSnnn 


Symbolic unit required only when no extent statement is provided 


X 


X 





ERREXT=YES 


Nondata transfer errors are to be indicated in ERRBYTE 


X 







FEOVD=YES 


Support for sequential disk end of volume records is desired 


X 







HOLD = YES 


Employ the tracl^ hold function 


X 


X 





DSKXTNT=n 


Indicates the number (n) of extents for a relative ID 


X 


X 





IDLOC=xxxxxxxx 


Name of field in which IOCS stores the ID of a record 


X 


X 


o 


KEYARG=xxxxxxx 


Name of l^ey field if READ filename,KEY; or WRITE filename.KEY; or WRITE 
filename,AFTER is used for this file 


X 


X 


o 


KEYLEN = nnn 


Number of bytes in record key if keys are to be processed. If omitted, IOCS 
assumes zero (no key) 


X 


X 





LABADDR =xxxxxxxx 


Name of your routine to check/write user labels 


X 


X 





MODNAME=xxxxxxxx 


Name of DAMOD logic module for this DTF. If omitted, IOCS generates 
standard name 


X 


"^ 





RDONLY=YES 


Generates a read-only module. Requires a module save area for each task 
using the module 


X 







READID=YES 


READ filename, ID macro is used for this file 


X 







READKEY=YES 


READ filename, KEY macro is used for this file 


X 


X 





RECFORM=xxxxxx 


(FIXUNB, SPNUNB, VARUNB, or UNDEF). If omitted, FIXUNB is assumed 


X 


X 





RECSIZE=(nn) 


Register number if RECFORM = UNDEF 


X 


X 





RELTYPE = xxx 


(DEC or HEX). Indicates decimal or hexadecimal relative addressing 


X 


X 





SEPASMB = YES 


DTFDA is to be assembled separately 


X 


X 





SRCHM=YES 


Search multiple tracks, if record reference is by key 




X 





TRLBL=YES 


Process trailer labels, LABADDR must be specified 




X 





VERIFY=YES 


Check disk records after they are written. 


X 


X 





WRITEID=YES 


WRITE filename, ID macro is used for this file 


X 


X 





WRITEKY = YES 


WRITE filename, KEY macro is used for this file 


X 


X 





XTNTXIT= xxxxxxxx 


Name of your routine to process extent information 



M = Mandatory 
0=Optional 

Figure 3-5. DTFDA macro. 

AFTER=YES: This operand must be included if 
any records (or an additional record) are written in a 
file by a formatting WRITE (count, key, and data) 
following the last record previously written on a 
track. The remainder of the track is erased. That is, 
whenever either of the macros 



WRITE filename,AFTER 
WRITE filename, RZERO 
is used in a program, this operand is required. 

BLKSIZE=n: This operand indicates the size of 
the I/O area by specifying the maximum number of 
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characters that are transferred to or from the area at 
any one time. When undefined, variable length or 
spanned records are read or written, the area must 
be large enough to accommodate the largest record. 

For details on how to compute n, see DOS/VSE 
Macro User's Guide, as Usted in the Preface. 

IOCS uses this specification to construct the count 
field of the CCW for reading or writing records. 

CONTROL=YES: Include this operand if a 
CNTRL macro is issued for this file. The CNTRL ma- 
cro for seeking on a disk allows you to specify a 
track address on which access movement should 
begin for the next READ or WRITE macro. While the 
arm is moving, you may process data and/or request 
I/O operations on other devices. 

DEVADDR=SYSnnn: This operand must specify 
the symbolic unit (SYSnim) associated with a file if 
the symboUc unit is not provided via an extent job 
control statement. If such a unit is provided, its 
specification overrides the devaddr parameter. 
This specification, or symbolic unit, represents an 
actual I/O address and is used in the ASSGN job con- 
trol statement to assign the actual I/O device address 
to the file. 

Note: EXTENT job cx>ntrol statements provided for DAM must 
be supplied in ascending order, and the symbolic units for multi- 
volume files must be assigned in consecutive order. 

DEVICE= (2311 |2314|3330|3340|33501:This 
operand specifies the device on which the file is lo- 
cated. If this operand is omitted, 231 1 is assumed. 
For devices supported by DOS/VSE and not in- 
cluded in the above operand specification, specify 
device codes as listed in Figure 3-6. 

Note: DAM does not permit the use of different size data mo- 
dules (on a 3340) for a multivolume file. 

DSKXTNT=n: This operand indicates the maxi- 
mum number of extents (up to 256) that are speci- 
fied for a file. When this operand is used together 



with FIXUNB, VARUNB, or UNDEF specified in the 
RECFORM Operand, it indicates that a rela.lve ID is 
used in the seekadr and idloc locations. If 
DSKXTNT=n is omitted, a physical ID is assumed in 
the SEEKADR and idloc locations. 

If RECFORM=SPNUNB is Specified, DSKXTNT is 
required. If relative addressing is used, the RELTYPe 
operand must also be specified. 

ERRBYTE=name: This operand is required for 
IOCS to supply indications of exceptional conditions 
to your program. The name of a 2-byte field (in 
which IOCS can store the error-condition or status 
codes) is entered. 

ERREXT=YES: This operand enables unrecovera- 
ble I/O errors (occurring before a data transfer takes 
place) to be indicated to your program. This error 
information is indicated in the bytes named in the 
ERRBYTE Operand and is available after the waitf 
macro has been issued. 

FEOVD=YES: This operand is specified if code is 
generated to handle end-of-volume records. It 
should be specified only when reading a file which 
was built using DTFSD and the FEOVD macro. 

HOLD=YES: This operand can be specified only if 
the track hold function is 

• specified at system generation time, 

• included in the DAMOD macro, and 

• used when the file is referenced. 

IDLOC=name: This operand is included if you 
want IOCS to supply the ID of a record after each 
READ or WRITE (ID or KEY) is completed. Specify 
the name of a record reference field in which IOCS is 
to store the ID. WAITF should be used before refer- 
encing this field. Do not specify the same field for 
IDLOC and seekadr. 



DEVICE = 
specification 


Device in use 


2311 


2314 


2319 


3330-1,2* 


3330-11** 


3340, 35MB 


3340, 70MB 


3350 


Default 


X 








X 






X 


2311 


X 








X 






X 


2314 




X 


X 




X 






X 


3330 








X 


X 






X 


3340 










X 


X 


X 


X 


3350 










X 






X 



* Also 3350 in 3330-1 compatibility mode. 

* * Also 3350 in 3330-1 1 compatibility mode. 

Figure 3-6. DEVICE= specifications for DTFDA. 
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IOAREAl=naine: This operand must be included 
to specify the name of the input/output area used 
for the file. IOCS routines transfer records to or from 
this area. The specified name must be the same as 
the name used in the DS instruction that reserves this 
area of storage. 

KEYARG=name: This operand must be included 
if records are identified by key: that is, if either of 
the macros 

READ filename,KEY 

WRITE filename,KEY 
is used in a program, this entry and the correspond- 
ing KEYLEN operand are required. KEYARG speci- 
fies the name of the key field in which you supply 
the record key to IOCS. 

The KEYARG operand is required for formatting 
WRITE (WRITE filename,AFTER) operations for files 
containing keys if recform=varunb or spnunb. It 
is required also when the macro 

READ filename,lD 
is specified and if KEYLEN is not zero. When record 
reference is by key, IOCS uses this specification at 
assembly time to construct the data address field of 
the CCW for search commands. 

KEYLEN=n: This operand must be included if 
record reference is by key or if keys are read or writ- 
ten. It specifies the number of bytes in each key. All 
keys must be the same length. If this operand is 
omitted, IOCS assumes a key length of zero. 

If there are keys recorded on DASD and this entry 
is absent, a WRITE ID or read id writes or reads the 
data portion of the record. 

When record reference is by key, IOCS uses this 
specification to construct the count field of the CCW 
for this file. IOCS also uses this in conjunction with 
lOAREAl to determine where the data field in the I/O 
area is located. 

LABADDR=name: You may require one or more 
user labels in addition to the standard file label. If 
so, you must include your own routine to check, or 
write, the labels. The name of such a routine is spec- 
ified in this operand. IOCS branches to this routine 
after it has processed the standard label. 

MODNAME=name: This operand specifies the 
name of the logic module that is used with the DTP 
table to process the file. If the logic module is as- 
sembled with the program, modnaME must specify 
the same name as the DAMOD macro. If this entry is 
omitted, standard names are generated for calling 
the logic module. If two DTP macros call for differ- 
ent functions that can be handled by a single mo- 
dule, only one module is called. 



RDONLY=YES: This operand is specified if the 
DTP is used with a read-only module. Each time a 
read-only module is entered, register 13 must con- 
tain the address of a 72-byte doubleword-aligned 
save area. Each task should have its own uniquely 
defined save area. Each time an imperative macro 
(except OPEN, OPENR, or lbret) is issued, register 13 
must contain the address of the save area associated 
with the task. The fact that the save ai 



u^wuo uxw uxix- 



que for each task makes the module reentrant, that 
is, capable of being used concurrently by several 
tasks. 

READID=YES: This operand must be included if, 
in your program, the macro READ filename, ID is 
used. 

READKEY=YES: This operand must be included 
if, in your program, the macro READ filename,KEY is 
used. 

RECFORM= (FIXUNB|SPNUNB|UNDEF| 

VARUNB}: 
This operand specifies the type of records in the 
input or output file. The specifications are: 

PIXUNB 

For fixed-length records. All records are con- 
sidered unblocked. If you want blocked re- 
cords, you must provide your own blocking 
and deblocking. 

SPNUNB 

For spanned records. This specification is for 
unblocked variable-length logical records of 
less than 32,768 bytes per record. 

UNDEP 

For undefined records. This specification is 
required only if the records are of undefined 
format. 

VARUNB 

For variable-length records. This specification 
is for unblocked variable-length records. 
For a defmition of record formats see DOS/ VSE 
Data Management Concepts, as listed in the Preface. 



RECSIZE=(r): This operand must be included if 
undefined records are specified (recporm=undep). 
It specifies the number of the general-purpose regis- 
ter (any of 2 through 12) that contains the length of 
each individual input or output record. 

Whenever an undefined record is read, IOCS sup- 
plies the length of the data area for that record in the 
specified register. 

When an undefined record is written, you must 
load the length of the data area of the record (in 
bytes) into this register, before you issue the write 
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macro for the record, iocs adds the length of the 
key when required. 

When records are written (after specified in the 
WRITE macro), iocs uses the length to construct the 
count area written on dasd. iocs adds the length of 
both the count and the key when required. 

RELTYPE= (DECIHEX): This operand specifies 
whether the zoned decimal (dec) or hexadecimal 
(hex) form of the relative ID is to be used. When 
FIXUNB, VaRUNb, or UNDEF is Specified in the 
RECFORM Operand, reltype should be suppUed 
only if the dskxtnt operand (relative ID) is speci- 
fied. If omitted, a hexadecimal relative ID is as- 
sumed. However, if DSKXTNT is also omitted, a 
physical ID is assumed in the seekadr and IDLOC 
addresses. 

If RECFORM=SPNUNB is Specified, the reltype 
operand is required when relative addressing is 
used. If reltype is omitted, a physical ID is as- 
sumed in the seekadr and iDLOC addresses. 



TRLBL=YES: This operand, if specified with the 
LABADDR Operand, indicates that user standard 
trailer labels are to be read or written following the 
user standard header labels on the user label track. 
Both operands must be specified for trailer label 
processing. For more information on processing 
labels, see "Label Processing" in DOS/ VSE Macro 
User's Guide, as listed in the Preface. 

TYPEFLE= (INPUTIOUTPUT) : This operand 
must be included to indicate how standard volume 
and file labels are to be processed, input indicates 
that standard labels are to be read; output indi- 
cates that standard labels are to be written. 

This entry is always required. 

VERIFY=YES This operand is included if you 
want to check the parity of disk records after they 
are written. If this operand is omitted, any records 
written on a disk are not verified. 



SEEKADR=name: This operand must be included 
to specify the name of your track-reference field. In 
this field, you store the track location of the particu- 
lar record read or written. IOCS refers to this field to 
determine which volume and which track contains 
the desired record. Whenever records are to be lo- 
cated by searching for a specified ID, the track- 
reference field must also contain the number of the 
record on the track. 

SEPASMB=YES: Include this operand only if the 
DTFDA will be assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and the filename to be defined as 
an ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the DTF is being 
assembled with the problem program and no 
CATALR card is punched. 

SRCHM=YES: If records are identified by key, 
this operand may be included to cause iocs to 
search multiple tracks for each specified record. The 
macros 

READ filename,KEY 

WRITE filename,KEY 
cause IOCS to search the track specified in the track- 
reference field and all following tracks in the cylin- 
der, until the record is found or the end of the cylin- 
der is reached. If the file ends before the end of the 
cylinder and the record is not found, the search con- 
tinues into the next file, if any, on the cylinder. EOC, 
instead of NRF, is indicated. Without srchm=yes, 
each search is confined to the specified track. 



WRITEID=YES: This operand must be included 
if the DASD storage location for writing any output 
record or updating an input file is specified by a 
record ID (identifier); that is, whenever the macro 

WRITE filename,lD 
is used in the program, this operand is required. 

WRITEKY=YES: This operand must be included 
if the DASD location for writing any output record or 
updating an input file is specified by record key, that 
is, whenever 

WRITE filename,KEY 
is used. 



XTNTXIT=name: This operand is included if you 
want to process label extent information. It specifies 
the name of your extent exit routine. During an 
OPEN, IOCS branches to your routine after each spec- 
ified extent is checked. Upon entering your routine, 
IOCS stores, in register 1, the address of a 14-byte 
field that contains the label extent information (in 
binary form) retrieved from the label information 
cylinder. If user labels are present, the user label 
track is returned as a separate extent and the lower 
limit of the first normal extent is increased by one 
track. The format of this field is shown in Figure 
3-7. Return to IOCS by use of the lbret macro. 
Registers 2 through 13 are available in the xtntxit 
routine. Within the routine you cannot issue a ma- 
cro that calls a transient routine (such as open, 

OPENR, CLOSE, CLOSER, DUMP, PDUMP, CANCEL, 
CHKPT, etc.). 
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Bytes 


Contents 





Extent type code (as specified in the extent 




statement) 


1 


Number of extent (as determined by ttie 




extent card sequence) 


2-5 


Lower limit of the extent (cchh) 


6-9 


Upper limit of the extent (cchh) 


10-11 


Symbolic unit number (in hexadecimal for- 


12-13 


Not used 



Figure 3-7 Label extent information field 
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DAMOD or DAMOD V Macro 



Operation 


Operand 


Remarks 


DAMOD' or 
DAMODV^ 
Must be in- 
cluded 


AFTER = YES 


When WRITE with the operand AFTER or RZERO is used 


ERREXT=YES 


Required if non-data-transfer error conditions are to be indicated in the ERRBYTE status bits 


FEOVD=YES 


Required if support for sequential disk end-of-volume records is desired 


HOLD = YES 


Required if the track hold function is to be used 


IDLOC=YES 


Required if IDLOC specified in DTFDA 


RDONLY=YES 


Required if a read only module is to be generated 


RECFORM = 
(FIXUNB'l 
UNDEF'l 
VARUNB^I 
SPNUNB^) 


Describes record format 


RELTRK=YES 


Required if the module is to process relative identifiers along with physical identifiers 


RPS = SVA 


To assemble RPS logic modules 


SEPASMB=YES 


If the module is assembled separately 


'. DAMOD is for fixed length unblocked and undefined records. 
^. DAMODV is for variable length and spanned unblocked records. 



Figure 3-8. DAMOD macro. 

AFTER=YES: This operand generates a logic mo- 
dule that can perform a formating write (count, 
key, and data). It performs the functions required 
by WRITE filename,AFTER; and write 
filename,RZERO. The module also processes any 
files in which the after operand is not specified in 
the DTP. 

HOLD=YES: This operand is specified if the track 
hold function is 

• specified at system generation time, and 

• included in the dtfda macro, and 

• used when the file is referenced. 

For more information see the dtfda hold ope- 
rand. 

ERREXT=YES: Include this operand if unrecov- 
erable I/O errors (occurring before a data transfer 
takes place) are to be indicated to your program in 
the bytes named in the DTF errbyte operand. 

FEOVD=YES: This operand is specified if coding 
is to handle end-of-volume records. It should be 
specified only if you are reading a file built using 
dtfsd and the feovd macro. 

IDLOC=YES: This operand generates a logic mo- 
dule that returns record identifier (id) information 
to you. The module also processes any files in which 
the IDLOC operand is not specified in the DTF. 

RDONLY=YES: This operand causes a read-only 



module to be generated. Whenever this operand is 
specified, any DTF used with the module must have 
the same operand. 

RECFORM= (FIXUNB |SPNUNB|UNDEF| 

VARUNB): 
If UNDEF is specified, the logic module generated 
can handle both unblocked fixed-length and unde- 
fined records. If the operand is omitted or if fixunb 
is specified, the logic module generated can handle 
only fixed-length unblocked records. If SPNUNB is 
specified, the module can handle both format v 
(variable length) and spanned format records. If 
VARUNB is specified, the module can handle only 
format V records. 

RELTRK=YES: This operand generates a logic 
module that can process with both physical and 
relative identifiers. If the operand is omitted, the 
module can process only with physical identifiers. 



RPS=SVA: This operand causes the RPS logic mo- 
dules to be assembled. 



SEPASMB=YES: Include this operand only if the 
module will be assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and the module name to be defined as an 
ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the module is 
being assembled with the problem program and no 
CATALR card is punched. 
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Standard DAMOD Names 

Each name begins with a 3-character prefix (IJI) and 
continues with a 5-character field corresponding to 
the options permitted in the generation of the mo- 
dule. 

DAMOD name = IJIabcde 

a = F RECFORM=FIXUNB 

— B RECFORivi-=UNDEF (handles both UNDEF and 

FIXUNB) 
= S RECFORM=SPNUNB 
= V RECFORM=VARUNB 

b = A AFTER=YES,RPS=SVA omitted 
= W AFTER=YES, RPS=SVA 
^ Z "'*i*ii'*'r is sDcciflcd 

c = E IDLOC=YES and FEOVD=YES 
= I IDLOC=YES 
= R FEOVD^YES 
= Z neither is specified 

d = H ERREXT=YES and RELTRK=YES 

= P ERREXT=YES 

= R RELTRK=YES 

= Z neither is specified 

e = W HOLD=YES and RDONLY=YES 
= X HOLD=YES 
= Y RDONLY=YES 
= Z neither is specified 



Subset/Superset DAMOD Names 

Figure 3-9 shows the subsetting and supersetting 
allowed for DAMOD names. Five parameters allow 
supersetting. For example, the module IJIBAIZZ is a 
superset of the module with the name IJIFAZZZ. 





+ 


+ 


+ 


+ 


+ 


IJI 
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X 
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2 


T 
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V 




E 
R 
Z 


H 
R 
Z 


Y 


-r Subsetting/supersciiing permitted. 



Figure 3-9. Subsetting and supersetting of DAMOD names. 

Notes: 

1. The module IJIBAEHW will cause assembly error message 
IPK154 TOO MANY ENTRY SYMBOLS 

The valid entry points for this module total more than 100, 
which is the maximum for assembler language. Specify less 
parameters for DAMOD if you can. Otherwise, you must 
assemble your own module for your program. 

2. Your program can have only one DAMOD for fixed un- 
blocked or undefined records and/or only one DAMOD for 
variable unblocked or spanned unblocked records; other- 
wise, duplicate name flagging occurs during assembly time. 
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DTFDIMacro 

The DTFDI macro provides device independence for system logical units. 



M 


DEVADDR=SYSxxx 


(SYSIPT, SYSLST, SYSPCH, or SYSRDR). System logical unit. 


M 


I0AREA1 =xxxxxxxx 


Name of first I/O area. 





CISIZE=n 


Size of FBA DASD control interval. 





EOFADDR = xxxxxxxx 


Name of your end-of-file routine. 





ERROPT = xxxxxxxx 


(IGNORE, SKIP, or name of your error routine). Prevents termination on errors. 





FBA=YES 


Specifies a Fixed Block Architecture device. 





10 AREA2 = xxxxxxxx 


If two I/O areas are used, name of second area. 





IOREG=(r) 


Register number. If omitted and 2 I/O areas are used, register 2 is assumed. General 
registers 2-1 2, written in parentheses. 





MODN AM E = xxxxxxxx 


DIMOD name for this DTF. If omitted, IOCS generates a standard name. Ignored with 
FBA DASD or 3800 advanced printer buffering. 





RDONLY=YES 


Generates a read-only module. Requires a module save area for each task using the 
module. 





RECSIZE=nnn 


Number of characters in record. Assumed values: 121 (SYSLST), 81 (SYSPCH), 80 
(otherwise). 





SEPASMB=YES 


DTFDI to be assembled separately. 





TRC=YES 


For 3800, output data lines include table reference character. 





WLRERR= xxxxxxxx 


Name of your wrong length record routine. 



M= Mandatory 
0= Optional 

Figure 3-10. DTFDI macro operands. 

DEVADDR= {SYSIPT|SYSLST|SYSPCH| 
SYSRDR): 

This operand must specify the symbolic unit associ- 
ated with this system file. Only the system names 
shown above may be specified. The logical device 
SYSLST must not be assigned to the 2560 or 
5424/5425. 

IOAREAl=name: This operand must specify the 
name of the input or output area used with the file. 
The input and/or output routines transfer records to 
or from this area. 

If the DTFDI macro is used to define a printer file, 
or a card file to be processed on a 2540, 2560, 3525, 
or 5424/5425, the first byte of the output area must 
contain a control character. 

CISIZE=n: This operand specifies the fba control 
interval size. The value n must be an integral multi- 
ple of the FBA logical block size and, if greater than 
8K, must be a multiple of 2K. The maximum value is 
32768 (32K), except when assigned to SYSLST or 
SYSPCH, when the maximum is 30720 (30K). 

If FBA=YES is specified, and CISIZE is omitted, 
CISIZE=0 is assumed. Control interval size may be 
overridden for an output file at execution time by 
specifying the cisiZE parameter of the dlbl control 
statement. For an input file, the cisiZE value in the 
format- 1 label is used. 



EOFADDR=name: This operand specifies the 
name of your end-of-file routine. It is required only 
if SYSIPT or SYSRDR is Specified. 

IOCS branches to this routine when it detects an 
end-of-file condition. In this routine, you can per- 
form any operations necessary for the end-of-file 
condition (you generally issue the CLOSE or CLOSER 
macro). 

IOCS detects the end-of-file condition by recog- 
nizing the characters /* in positions 1 and 2 of the 
record for cards, a tapemark for tape, and end-of- 
file record for disk. If the system logical units 
SYSIPT and SYSRDR are assigned to a 5424/5425, 
IOCS requires that the /* card, indicating end-of-file, 
be followed by a blank card. An error condition 
results if the records are allowed to run out without 
a /* card (and without a /& card, if end-of-job). 
IOCS detects the end-of-file condition on diskette 
units by recognizing that end-of-data has been 
reached on the current volume and that there are no 
more volumes available. 

ERROPT= (IGNORE|SKIP|name}: This ope- 
rand does not apply to output files. For output files 
for most devices, the job is automatically terminated 
after iocs has attempted to retry writing the record; 
for 2560 or 5424/5425 output files, normal error 
recovery procedures are followed. 
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This operand applies to wrong-length records if 
WLRERR is omitted. If both erropt and wlrerr 
are omitted and wrong-length records occur, iocs 
ignores the error. 

ERROPT specifies the function to be performed for 
an error block. If an error is detected when reading 
a magnetic tape, or a disk or a diskette volume, IOCS 
attempts to recover from the error. If the error is not 
corrected, the job is terminated unless this operand 
is included to specify other procedures to be taken. 
The three specifications are described below. 

IGNORE 

indicates that the error condition is to be ig- 
nored. The address of the error record is made 
available to you for processing (see CCB 
Macro). 



SKIP 



name 



indicates that the error block is not to be made 
available for processing. The next record is 
read and processing continues. 

indicates that IOCS is to branch to your routine 
when an error occurs, where you may perform 
whatever functions are desired or simply note 
the error condition. The address of the error 
record is supplied in register 1. The contents of 
the lOREG register may vary and should not be 
used for error records. Also, you must not is- 
sue any GET instructions in your error routine. 
If you use any other IOCS macros, you must 
save the contents of register 14. If 
RDONLY=YES is specified, or if the file is as- 
signed to an FBA device, you must also save the 
contents of register 13. At the end of the error 
routine, return to IOCS by branching to the 
address in register 14. The next record is then 
made available for processing. 



FBA=YES: Specifies a Fixed Block Architecture 
device. If used, MODNAME specification is ignored 
and an IBM-supplied module is used. 

IOAREA2=name: Two input or output areas can 
be allotted for a file to permit overlapped GET or 
PUT processing. If this operand is included, it speci- 
fies the name of the second I/O area. 

IOREG=(r): When two I/O areas are used, this 
operand specifies the general purpose register (any 
of 2 through 12) that points to the address of the 
next record. For input files, it points to the logical 
record available for processing. For output files, it 
points to the address of the area where you can build 
a record. If omitted, and two I/O areas are used, 
register 2 is assumed. 



MODNAME=name: This operand may be used to 
specify the name of the logic module used with the 
DTP table to process the file. If the logic module 
(DIMOD) is assembled with the program, the 
MODNAME parameter in this DTP must specify the 
same name as the DIMOD macro. 

If this entry is omitted, standard names are gener- 
ated for calling the logic module. If two different 
DTP macros call for different functions that can be 
handled by a single module, only one standard- 
named module is called. 

RDONLY=YES: This operand is specified if the 
DTP is to be used with a read-only module. Each 
time a read-only module is entered, register 13 must 
contain the address of a 72-byte doubleword-aligned 
save area. Each task should have its own uniquely 
defined save area, and each time an imperative ma- 
cro (except OPEN, OPENR or lbret) is issued, register 
13 must contain the address of the save area associ- 
ated with that task. The fact that the save areas are 
unique for each task makes the module reentrant 
(that is, capable of being used concurrently by sever- 
al tasks). 

If an erropt or wlrerr routine issues i/o mac- 
ros using the same read-only module that caused 
control to pass to either error routine, the program 
must provide another save area. One save area is 
used for the initial I/O operations, and the second for 
I/O operations in the ERROPT or WLRERR routine. 
Before returning to the module that entered the er- 
ror routine, register 13 must be set to the save area 
address originally specified for the task. 

If the operand is omitted, the module generated is 
not reenterable and no save area need be estab- 
lished. 

RECSIZE=n: This operand specifies the length of 
the record. For input files (SYSIPT and SYSRDR), the 
maximum allowable record size is 80 bytes. For 
output files, RECSIZE must include one byte for con- 
trol characters. The maximum length specification 
is 121 for SYSLST and 81 for SYSPCH. 

For disk files, 121 must be specified for SYSLST, 
and 81 for SYSPCH to assure device independence. 
For printers and punches, DIMOD assumes a 
s/370-type control character if the character is not a 
valid ASA character. The program checks ASA con- 
trol characters before s/370-type control characters. 
Therefore, if it is a valid ASA control character (even 
though it may also be a S/370-type control character), 
it is used as an ASA control character. Otherwise, it 
is used as a S/370-type control character. 

Control character codes are listed in DOS/ VSE 
Macro User's Guide; note, however: 
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• 2520 stacker selection codes must be used for 
the 1442. 

• 2540 stacker selection 3 must not be used if 

device independence is to be maintained. 

If this operand is omitted, the following is assumed: 
80 bytes for SYSIPT. 

80 bytes for SYSRDR. 

81 bytes for SYSPCH. 
121 bytes for SYSLST. 

The use of assumed values for the recsize ope- 
rand assures device independence. For disk and 
diskette files, the assumed values are required to 
assure device independence. 

SEPASMB=YES: Include this operand only if the 
DTFDI will be assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and defines the filename as an 
ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the dtp is being 
assembled with the problem program and no 
CATALR card is punched. 



TRC=YES: This operand applies to the IBM 3800 
Printing Subsystem. TRC=YES specifies that a table 
reference character is included as the first byte of 
each output data line (following the optional print 
control character). The printer uses the table refer- 
ence character (0, 1, 2, or 3) to select the character 
arrangement table corresponding to the order in 
which the table names have been specified with the 
CHARS parameter on the setprt job control state- 
ment (or SETDRT macro instruction). 

If the device allocated is not a printer and 
TRC=YES is specified, the table reference character is 
treated as data when a PUT is issued. If the device is 
a non-3800 printer, the table reference character is 
removed and not printed. 

WLRERR=name: This operand applies only to 
input files on devices other than diskette units. It 
specifies the name of your routine to which IOCS 
branches if a wrong-length record is read on a tape 
or disk device. 
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DIMOD Macro 

Listed here are the operands you can specify for 
DIMOD. The header card contains DIMOD in the 
operation field and may contain a module name in 
the name field. If the module is omitted, IOCS gener- 
ates a standard module name. 

IOAREA2=YES: Include this operand if a second 
I/O area is needed. A module with this operand can 
be used with DTFDIS specifying either one or two I/O 
areas. If the operand is omitted or is invaUd, one I/O 
area is assumed. 

RDONLY=YES: This operand causes a read only 
module to be generated. Whenever this operand is 
specifed, any DTF used with the module must have 
the same operand. 

RPS=SVA: This operand causes the RPS logic mo- 
dules to be assembled. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and defined the module name as an ENTRY 
point in the assembly. If the operand is omitted, the 
assembler assumes that the module is being assem- 
bled with the DTF and the problem program and no 
CATALR card is punched. 

TRC=YES: Include this operand to specify wheth- 
er the module is to test the table reference character 
indicator in the DTFDI or ignore that indicator. If 
TRC=YES is specified, the generated module can 
process output files with table reference characters 
and those without. If the TRC operand is specified, 
TYPEFLE= INPUT must not be specified. 

TYPEFLE= (OUTPUT'iINPUT): Include this 
operand to specify whether the module is to process 
input or output files. If OUTPUT is specified, the 
generated module can process both input and output 
files. 



Standard DIMOD Names 

Each name begins with a 3-character prefix (IJJ) 
followed by a 5-character field corresponding to the 

options permitted in the generation of the module. 



DIMOD name = IJJabcde 



= F 



C RPS=SVA is not specified 

V RPS=SVA 

B TYPEFLE=OUTPUT (both input and output) 

I TYPEFLE=INPUT 



d = I I0AREA2=YES 

= Z I0AREA2=YES is not specified 

e = C RDONLY=YES 

= D RDONLY= YES is not specified 



Subset/Superset DIMOD Names 

Figure 3-11 illustrates the subsetting and superset- 
ting allowed for DIMOD names. All of the operands 
except TRC=YES allow subsetting. A module name 
specifying B is a superset of the module specifying I: 
for example. IJJFFCBID is a superset of the module 

IJJFCIID. 

The IBM-supplied preassembled logic modules do 
not have TRC=YES. The system programmer can 
reassemble them with TRC=YES to support 3800 
table reference characters. Although the code that is 
generated for a module assembled with TRC=YES is 
different from the code that is generated for a mo- 
dule with TRC=NO, the module name is the same. If 
some, but not all DIMOD logic modules are reassem- 
bled this way, it may interfere with subsetting or 
supersetting. 



+ + * 

IJJFCBIC 
I Z D 



+ Subsetting/supersetting permitted. 
* No subsetting/supersetting permitted. 



Figure 3-11. Subsetting and supersetting of DIMOD names. 
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DTFDR Macro 

You must use the dtfdr macro to define each 3886 file in your program. 



M 


DEVADDR=SYSxxx 


Symbolic unit assigned to 3886 optical character reader. 


M 


FRNAME=xxxxxxxx 


Phase name of format record to be loaded upon file opening. 


M 


FRSIZE=nn 


Number of bytes to be reserved in DTF expansion for format records. 


M 


EXITING =xxxxxxxx 


Name of completion code return area. 


M 


I0AREA1 =xxxxxxxx 


Name of file input area. 


M 


HEADER = xxxxxxxx 


Name of area for header record from 3886. 


M 


EOF ADDR = xxxxxxxx 


Address of your end-of-file routine. 


M 


COREXIT= xxxxxxxx 


Name of your error condition routine. 





DEVICE =3886 


If omitted, 3886 is assumed. 





RDONLY=YES 


If DTF is to be used with read-only module. 





MODNAME=xxxxxxx 


Name of DRMODxx logic module for this DTF. If omitted, IOCS generates standard 
name. 





BLKSIZE=nnn 


Length of area named by I0AREA1 . If omitted, the maximum length of 1 30 is assumed. 





SEPASMB =YES 


If DTFDR is to be assembled separately. 





SETDEV=YES 


If SETDEV macro is issued in your program to load a different format record into the 
3886. 



M = Mandatory 
0=Otional 

Figure 3-12. DTFDR macro operands. 

DEVADDR=SYSnnn: Specifies the symbolic unit 
to be associated with the logical file. The symbolic 
unit (SYSnnn) is associated with an actual I/O device 
through the job control ASSGN statement. 

FRN AME=phasename: Specifies the phase name 
of the format record to be loaded when the file is 
opened. 

FRSIZE=number: Specifies the number of bytes to 
be reserved in the DTF expansion for format records. 
The number must equal at least the size of the larg- 
est DFR macro expansion and its associated DLINT 
macro expansions, plus four. This size is printed in 
the ninth and tenth bytes of the DFR macro expan- 
sion. 

If you use the SETDEV macro in your program to 
change format records, you can reduce the Ubrary 
retrieval time by specifying a size large enough to 
contain all the frequently used format records. The 
area should then be equal to the sum of the format 
record sizes, plus four bytes for each format record. 
When the SETDEV macro is issued, the format record 
is loaded into this area from the core image library if 
it is not already present in the area. 

EXITIND=name: Specifies the symbolic name of 
the 1-byte area in which the completion code is re- 
turned to the COREXIT routine for error handling 
from an I/O operation. 
The completion codes are: 



Code 
Dec Hex 

240 X'FO' 



241 
242 



243 
244 

249 



X'F1' 
XF2' 



X'F3' 
X'F4' 

X'F9' 



Meaning 

No errors occurred. (This code should 
not be present when the COREXIT routine 
receives control.) 

Line mark station timing mark check 
error. 

Nonrecovery error. Do not issue the 
CNTRL macro to eject the document from 
the machine. Have the operator remove 
the document. 

Incomplete scan. 

Line mark station timing mark check and 

equipment check. 

Permanent error. 



Note: If any of these errors occur while the file is being opened, 
the COREXIT routine does not receive control and the job is 
canceled. 



IOAREAl=name: Specifies the symbolic name of 
the input area to be used for the file. The area must 
be as large as the size specified in the BLKSIZE par- 
ameter. If BLKSIZE is not specified, the input area 
must be 130 bytes. 

HEADER=name: Specifies the symbolic name of 
the 20-byte area to receive the header record from 
the 3886. 

EOFADDR=name: Specifies the symbolic address 
of your end-of-file routine. LIOCS branches to this 
routine whenever end of file is detected on the 3886. 
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COREXIT=name: Provides the symbolic name of 
your error correction routine. LIOCS branches to this 
routine whenever an error is indicated in the 
EXITIND byte. 

You can attempt to recover from various errors 
that occur on the 3886 through the COREXIT routine 
you provide. Your cOREXiT routine receives control 
whenever one of the following conditions occurs: 

• Incomplete scan 

• Line mark station timing mark check error 

• Nonrecovery error 

• Permanent error 

Note: If any of these errors occur while the file is being opened, 
the COREXIT routine does not receive control and the job is 
canceled. 

Figure 3-13 describes normal functions for the 
COREXIT routine for the various error conditions 
and provides the exits that must be taken from the 
COREXIT routine. 

Error messages are provided to describe errors to 
the operator during program execution. 

DEVICE=3886: Indicates that 3886 is the I/O de- 
vice for this file. This operand may be omitted. 

RDONLY=YES: This operand is specified if the 
DTP is used with a read-only module. Each time a 
read-only module is entered, register 13 must con- 
tain the address of a 72-byte doubleword-aligned 
save area. Each DTP should have its own uniquely 
defined save area. 

Each time an imperative macro (except OPEN or 
OPENR) is issued using a particular DTP, register 13 
must contain the address of the save area associated 
with that DTP. The fact that the save areas are uni- 
que or different for each task makes the module 



reentrant (that is, capable of being used concurrent- 
ly by several tasks). 

If a COREXIT routine issues I/O macros using the 
same read-only module that caused control to pass 
to either error routine, your program must provide 
another save area. One save area is used for the 
normal I/O operations, and the second for i/o opera- 
tions in the COREXIT routine. Before returning to 
the module that entered the COREXIT routine, regis 



ter 13 must contain the save area address originally 
specified for that DTP. 

If this operand is omitted, the module generated 
is not reenterable, and no save area is required. 

MODNAME=name: This operand may be used to 
specify the name of the logic module used with the 
DTP table to process the file. If the logic module 
(drmod) is assembled with the program, the 
MODNAME parameter in this DTP must specify the 
same name as the drmod macro. 

If this entry is omitted, standard names are gener- 
ated for calUng the logic module. If two different 
DTP macros call for different functions that can be 
handled by a single module, only one standard- 
named module is called. 

BLKSIZE=nnn: Specifies the length of the area 
named by the lOAREAl keyword. The length of the 
area must be equal to the length of the longest re- 
cord to be passed from the 3886. 

If this operand is omitted, the maximum length of 
130 is assumed. 

Note: DOS/VSE LIOCS does not allow you to block records 
read from the 3886. 

SEPASMB=YES: Specifies that the DTP will be 
assembled separately. If this operand is specified, a 
CATALR card with the filename is punched before 



Error 


Normal COREXIT Function 


Exit to 


X'F2' 


Eliminate the data that has been read from this docu- 
ment and prepare to read the next input document 
(See Note 1 ). 


Routine in your program to read the next document. 


X'F4' or 
X'F9' 


Do whatever processing is necessary before the job is 
canceled. (See Note 1). 


Your end-of-job routine. 


X'F1' 


Do any processing that may be required. The docu- 
ment may have been read incorrectly; you may want to 
delete all data records from the document (see Note 
2). 


Branch to the address in register 1 4 to return to the in- 
struction following the macro causing the error. 


X'F3' 


Rescan the line using another format record or using 
image processing and editing the record in your pro- 
gram (see Note 2). 


Branch to the address in register 1 4 to return to the in- 
struction following the macro causing the error. 


Note 1: If in your COREXIT routine, you issue an I/O macro to the 3886 and an error occurs during that operation, control is 
returned to the beginning of the COREXIT routine. You must take precautions in the COREXIT routine to prevent looping in this 
situation. If no errors occur, control returns to the instruction following the I/O macro. 

Note 2: If, in your COREXIT routine, you issue an I/O macro to the 3886, control always returns to the instruction following the 
macro. You should then check the completion code to determine the outcome of the operation. 



Figure 3-13. COREXIT routine functions. 
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the deck and the filename is defined as an entry SETDEV=YES: Specifies that the SETDEV macro 

point for the assembly. is issued in your program to load a different format 

record into the 3886. 
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DRMOD Macro 

Listed here are the operands you can specify for 
DRMOD. The first card contains DRMOD in the oper- 
ation field and may contain a module name in the 
name field. 



SETDEV=YES: Is specified if the SETDEV macro 
may be used when processing a file with this I/O 
module. If SETDEV=YES is specified in the drmod 
macro but not in the dtfdr macro, the SETDEV 
macro cannot be used when processing that file. 



DEVICE=3886: Specifies that the 3886 is the input 
device. This operand may be omitted. 

SEPASMB=YES: Must be specified if the I/O 
module is assembled separately. This entry causes a 
CATALR card to be punched preceding the module. 

RDONLY=YES: This operand generates a read 
only module. RDONLY=YES must also be specified 
in the DTP. For additional programming require- 
ments concerning this operand, see the dtfdr 
RDONLY operand. 



Standard DRMOD Names 

Each name consists of eight characters. They are: 
iJMZxxDO. The fifth and sixth characters are varia- 
bles as follows: 

• If SETDEV=YES is Specified, the fifth character 
is S; otherwise it is z. 

• If RDONLY=YES is specified, the sixth character 
is R; otherwise it is z. 

Note: Subsetting/supersetting is allowed with the SETDEV 
keyword, but not with the RDONLY keyword. 
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DFR Macro 

The DFR macro defines attributes common to a group of line types. 



M 


FONT=xxxx 


Default font for all codes described by format record. 





REJECT =x 


Replacement character for any reject character in the data record read by the 3886. If 
omitted, X'3F' is assumed. 





ERASE=YES 


Group and character erase symbols are to be recognized. If omitted, NO is assumed. 





CHRSET=n 


Specifies recognizing character (see Figure 3-15). If omitted, is assumed. 





EDCHAR=(x, ..) 


Characters that may be deleted from any field that is read. If omitted, no character 
deletion occurs. 





BCH=n 


Batch numbering is to be preformed by 3886. If specified, BCHSER is invalid. 





BCHSER=n 


Both batch and serial numbering are to be performed. If specified, BCH is invalid. 





NATNHP=YES 


European Numeric Hand Printing (ENHP) characters 1 and 7 are used. If omitted, NO is 
assumed, indicating that Numeric Hand Printing (NHP) character 1 + 7 are used. 



M= Mandatory 
0= Optional 

Figure 3-14. DFR macro operands. 

FONT =code: Specifies the default font for all 
fields described by the format record. The default 
font is used to read a field unless another font is 
specified for an individual field through the dlint 
macro. This is the only required operand in the dfr 
macro. The vahd codes and the fonts they represent 
are: 

NUMA Numeric OCR-A font 

ANAl Alphameric OCR-A font (mode 1) 

ANA2 Alphameric OCR-A font (mode 2) 

NUMB Numeric OCR-B font (mode 3) 

ANB 1 Alphameric OCR-B font 

NHP 1 Numeric hand printing (normal mode) 

NHP2 Numeric hand printing (verify mode) 

GOTH Gothic font 

MRKA Mark OCR-A font 

MRKB Mark OCR-B font 

For a description of these fonts, see the appropri- 
ate IBM 3886 device manuals. 

REJECT = character: Indicates the character that 
is to be substituted in the data record for any reject 
character read by the device. If this operand is omit- 



ted, X'3F' is assumed. Reject characters are charac- 
ters that are not recognizable by the device. 

Note: This note applies to the keywords REJECT and ED- 
CHAR. Aphostrophes enclosing the character are optional for all 
characters except special characters used in macro operands. For 
a description of these characters, see OS/VS-DOS/VSE-VM/370 
Assembler Language , as Usted in the Preface. 



ERASE = {YES|NO}: Specifies whether group 
and character erase symbols are to be recognized as 
vahd symbols. If this operand is not specified, NO is 
assumed. For more information on group and char- 
acter erase symbols, see the appropriate IBM 3886 
device manuals. 



CHRSET = {0|1|2|3|4|5): Specifies which one of 
the options in Figure 3-15 is to be used for recogniz- 
ing characters. If this operand is not entered, is 
assumed. 
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OCR-A 


OCR-B 






Numeric 






Numeric 


Alphameric 


Mode 


Alphameric Modes 


Mode 


Mode 


Hexa- 


Format 


Highspeed 


Model 






Printers or 


(Highspeed) 


Mode 2 


Highspeed Printers 


decimal 


Record 


Typewriters 


Printer) 


1 T%#r\Oit*«»i**»i« 1 


cr lYpsVirrSiers 


v>ode 


Ccdss 


$ 


$ 


^ 


$ 


$ 


5B . 


00 


£ 


i 


f 


£ 


£ 


5B 


01 


¥ 


¥ 


¥ 


¥ 


¥ 


5B 


02 




N 


N 




Ri 


78 




$ 


$ 


$ 


$ 


$ 


58 


03 




s 


a 




a 


58 






)E 


;e 




/E 


78 

















7C 


04 


$ 


$ 


$ 




U Note 


58 






>( 


X 




A 


78 






b' 


« 




b 


7C 
















FO 


05 



Note: In OCR-A font the U Is coded as a zero and should be used only in 
alphabetic fields. 



Figure 3-15. Character set option list. 

EDCHAR = (x,...): Specifies up to six characters 
that may be deleted from any field that is read. The 
EDCHAR parameter in the EDiTn keyword of the 
DLINT macro controls this function for individual 
fields. If this operand is omitted, no character dele- 
tion is performed. See the note under the REJECT 
operand discussion for characters that must be speci- 
fied in quotes. For example, to specify the charac- 
ters &, >, and ), you would code 

EDCHAR=('&','>',')'). 

BCH = {1|2|3}: Indicates that batch numbering is 
to performed by the 3886. Specifying 1, 2, or 3 indi- 
cates that documents routed to a stacker are to be 
batch numbered. Specifying 1 indicates stacker a, 2 
indicates stacker B, 3 indicates both stackers. If this 
operand is specified, the BCHSER operand is invalid. 
If neither BCH nor BCHSER are entered, no batch 
numbering is performed. This operand is valid only 
if the serial numbering feature is installed on the 
3886. For more information on batch numbering, 
see the appropriate IBM 3886 device manuals. 



RCHSER = {1|2|3}: Indicates that both batch and 
serial numbering are to be performed by the 3886. 
Specifying 1, 2, or 3 indicates that documents routed 
to a stacker are to be batch and serial numbered. 
Specifying 1 indicates stacker A, 2 indicates stacker 
B, 3 indicates both stackers. If this operand is speci- 
fied, the BCH operand is invalid. If neither BCH nor 
BCHSER is specified, batch and serial numbering are 
not performed. This operand is valid only if the 
serial numbering feature is installed on the 3886. 
For more information on batch and serial number- 
ing, see the appropriate IBM 3886 device manuals. 

NATNHP = {YES|NO}: Specifies which of the 
numeric hand printing character set options are used 
for the numbers 1 and 7. yes indicates that the Eu- 
ropean Numeric Hand Printing (ENHP) characters 1 
and 7 are used; NO indicates the Numeric Hand 
Printing (NHP) characters 1 and 7 are used. If this 
operand is not entered, NO is assumed. 
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DLINT Macro 

The DLINT macro describes one line type in a format group and the individual fields in the Une. 



M 


LFR = nn 


Line format record for the line. 


M 


LINBEG=nn 


Specifies beginning of a line. 





IMAGE=YES 


Data record is to be in image mode. If omitted, NO (standard mode) is assumed. 





NOSCAN=(n.n) 


Indicates an area on the document line that is to be ignored by the 3886. 





FLDn=(n,n,NCRIT,xxx) 


Describes a field in a line, n in the FLD keyword may be from 1 to 14; if specified, a 
corresponding EDITn keyword must follow each FLDn keyword. 





EDITn=(xxxxxx,EDCHAR) 


Specifies editing functions to be performed on the data by 3886. A corresponding FLDn 
keyword must precede each EDITn keyword. 





FREND=YES 


Indicates last DLINT macro for the format record. If omitted, NO is assumed meaning that 
further DLINT macros follow. 



M = Mandatory 
0= Optional 

Figure 3-16. DLINT macro operands. 

Line Information Entries 

LFR=number This operand is required. It specifies 
the line format record number for the Une. The dec- 
imal number specified must be in the range of 
through 63. 

The line format record describes the format of 
one type of line; the line format record number is 
used to identify the line format record. This number 
is specified in the READ macro when you read a line 
of data from a document. 

LINBEG=number: This operand is required. It 
specifies the beginning of a line. The beginning 
position is the distance, measured in units of 0. 1 inch 
(2.54 mm), from the left edge of the document to the 
left boundary of the first field. The Umiting range of 
this position is 4 to 85. 

IMAGE= (YES|NO) : This operand specifies 
whether the data record should be in standard mode 
(lMAGE=NO), or image mode (image=yes). If this 
operand is not specified, lMAGE=NO is assumed. 

NOSCAN=(field-end,...)« Specifies an area on the 
document line that is to be ignored by the 3886. The 
parameter field-end is a decimal number indicating 
the distance, measured in units of 0. 1 inch (2.54 
mm), from the left edge of the document to the right 
end of the NOSCAN field. The field immediately to 
the left of the noscan field must end with an ad- 
dress delimiter rather than a character delimiter. 

Field Information Entries 

FLDn=({address-delimiter| character-delimiter) 
,irield-lengthl[,{NCRIT|font-code| 
NCRIT,font-code} )): 



Describes each of the fields in a Une. The n suffix is 
a number from 1 through 14 and the parameters are 
the same for keywords FLDi through FLDI4. The 
following rules apply when specifying these key- 
words: 

• Fields may be described in any order in the 
macro. 

• Each EDITn parameter must foUow its associat- 
ed FLDn parameter. 

• The n suffix need not be 1 for the first field in 
the line; however, the n suffix must increase for 
each field from left to right on the document 
Une. 

address-delimiter is a decimal number that speci- 
fies the distance, measured in units of 0.1 inch (2.54 
mm), from the left edge of the document to the right 
end of the field being defined. The last field in a Une 
must end with an address delimiter. 

character delimiter specifies the character that 
indicates the end of a field. The character delimiter 
is not considered part of the data; it is not included 
in the data record nor used in determining the 
length of the field. 

Apostrophes enclosing the characters are optional 
for all characters except through 9, and the special 
characters used in macro operands. For these char- 
acters, the apostrophes are required. For a descrip- 
tion of these characters, see OS/VS-DOS/VSE- 
VM/ 370 Assembler Language, as listed in the Pre- 
face. 

If a field ends with a character delimiter, the next 
field must be read using a font from the same font 
group. The font groups are: 

• NPHl, NPH2,GOTH 

• ANAl, ANA2, NUMA, MRKA 

• NUMB, MRKB 

• ANBl 
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field-length is a decimal number specifying the 
length of the field in the edited record. The length 
specified cannot be less than 1 or more than 127. If 
iMAGE=NO is specified, this parameter is required; if 
IMAGE=YES is specified, this parameter is invalid. 
The length specified in this parameter refers to the 
length of the field after any EDiTn options have been 
performed. The sum of the field lengths for a line 






NCRIT indicates that this is not a critical field. If 
this parameter is omitted, the field is assumed to be 
critical. 

font-code specifies a font for this field, different 
from the font specified in the DFR macro. If this 
parameter is not specified, the font specified in the 
DFR macro is used for the field. For information 
about the valid codes, see the DFR macro descrip- 
tion. 

EDITn=( (code|EDCHAR|code,EDCHAR) ): 

Describes the editing functions to be performed on 
the data by the 3886. 

The parameters are the same for keywords EDiTi 
through EDITH. There must be a FLDn keyword 
corresponding with each EDiTn keyword you 
specify. If an EDiTn keyword is specified, a code, 
EDCHAR, or both must be specified. When image 
mode is used, the EDiTn keywords are invalid. 

When the editing functions are completed and 
the field is greater than the specified length, the field 
is truncated from the right and the wrong length 
field indicator is set on in the header record. If only 
blanks are truncated, the wrong length field indica- 
tor is not set. 



code specifies the blanks to be removed and the 
fill characters to be added to the field, if any. The 
valid codes and their meanings are: 

Code Meaning 

HLBLOF All high- and low-order blanks are removed, the 
data is left justified, and the field is padded with 
blanks on the right (see Note). 

ALBLOF All blanks are removed from the data, the data is 
left-justified, and the field is padded with blanks 
on the right. 

NOBLOF No blanks are removed, the data is left-justified, 
and the field is padded on the right with blanks. 

HLBHIF All high- and low-order blanks are removed, the 

data is right-justified, and the field is padded to 
the left with EBCDIC zeros (X'FO) (see Note). 

ALBHIF All blanks are removed, the data is right- 

justified, and the field is padded with EBCDIC 
zeros (X'FO) on the left. 

ALBNOF All blanks are removed; the data must be equal 
in length to the field length specified. No pad- 
ding is done. 

Note: Two consecutive embedded blanks is the maximum num- 
ber sent. 

If the EDiTn keyword is omitted or if EDiTn is 
specified and the code is omitted, ALBLOF is as- 
sumed. 

EDCHAR indicates that the characters specified in 
the EDCHAR keyword of the DFR macro are to be 
deleted from the field. If this parameter is omitted, 
the characters are not deleted. 

FREND= (YESjNO} : Indicates whether this is the 
last DLINT macro for the format record. NO indi- 
cates that more DLINT macros follow; YES indicates 
that this is the last one. If this operand is omitted, 
NO is assumed. 
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DTFDU Macro 

The DTFDU macro defines sequential (consecutive) processing for a file contained on a diskette. 



Applies to 








Input 


Output 




X 




M 


EOFADDR =xxxxxxxx 


Name of your end-of-file routine. (Required for input only). 


X 


X 


M 


I0AREA1 =xxxxxxxx 


Name of first I/O area. 


X 


X 


M 


RECSiZE^nnn 


Length of one record in bytes. 


X 


X 





CMDCHN=nn 


Number of read /write CCWs (records) to be 
command-chained. 


X 


X 





DEVADDR=SYSxxx 


Symbolic unit, required only when not provided on an EXTENT 
statement. 


X 


X 





DEVICE =3540 


Must be 3540. If omitted, 3540 is assumed. 


X 


X 





ERREXT=YES 


Indicates additional errors and ERET desired. Specify 
ERROPT. 


X 


X 





ERROPT=xxxxxxxx 


IGNORE, or SKIP, or name of error routine. 


X 


X 





FEED=xxx 


YES means feed at end-of-file. NO means no feed, YES 
assumed if omitted. 




X 





FILESEC=YES 


YES means create file secure. 


X 


X 





IOAREA2=xxxxxxxx 


Name of second I/O area, if two areas are used. 


X 


X 





IOREG=(nn) 


Register number. General register 2 to 1 2 in parentheses. 
Omit WORKA. 


X 


X 





MODNAME=xxxxxxxx 


Name of DUMODFx logic module for this DTF. If omitted, IOCS 
generates standard name. 


X 


X 





RDONLY=YES 


Generates a read-only module. Requires a module save area 
for each task using the module. 


X 


X 





SEPASMB=YES 


DTFDU is to be assembled separately. 


X 


X 





TYPEFLE=xxxxxx 


INPUT or OUTPUT. If omitted. INPUT is assumed. 


X 







VERIFY=YES 


3741 /3742 input is verified. 


X 







VOLSEQ=YES 


YES means OPEN is to check sequencing of multi-volume files. 


X 


X 





WORKA=YES 


GET or PUT specifies work area. Omit lOREG. 




X 





WRTPROT=YES 


File will be created with Write-Protect on (cannot be 
overwritten). 



M= Mandatory 
0= Optional 

Figure 3-17. DTFDU macro operands. 

CMDCHN=nn: This operand is specified to indi- 
cate the number of Read/Write CCWs to be com- 
mand chained. VaUd entries are 1,2, 13, or 26; 1 is 
assumed if this operand is omitted. For each ccw 
specified by this operand, one record is processed 
(for example, if you code CMDCHN=13, 13 records 
are command chained and are processed - read or 
written - as a group). For entries of 2, 13, or 26, 



either the lOREG operand or the WORKA operand 
must be specified. 

DEVADDR=SYSxxx: This operand specifies the 
symbolic unit (SYSxxx) associated with the file if an 
EXTENT job control statement is not provided. An 
EXTENT statement is not required for single-volume 
input files. If an EXTENT statement is provided, its 
specification overrides any DEVADDR specification. 
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SYSxxx represents an actual I/O device address, and 
is used in the assgn job control statement to assign 
the actual I/O device address to this file. 

DEVICE=3540: This operand specifies that the file 
to be processed is on the 3540. This operand may be 
omitted. 

EOFADDR=naine: This operand specifies the 
symbolic name of your end-of-file routine. IOCS 
automatically branches to this routine on an end-of- 
file condition. You can perform any operations re- 
quired for the end-of-file in this routine (you will 
generally issue the CLOSE or CLOSER, macro). 

ERREXT=YES: This operand enables your 
ERROPT routine to return to DUMODFx with the 
ERET macro. It also enables permanent errors to be 
indicated to your program. For errext facilities, 
the EROPT operand must be specified. However, to 
take full advantage of this option, use the 
ERROPT=name operand. 

ERROPT={IGNORE|SKIP|name}: Specify this 
operand if you do not want a job to be terminated 
when a permanent error cannot be corrected in the 
diskette error routine. If attempts to reread a chain 
of records are unsuccessful, the job is terminated 
unless the ERROPT entry is included. Either ignore, 
SKIP, or the name of an error routine can be speci- 
fied. The functions of these parameters are de- 
scribed below. 

IGNORE 

The error condition is ignored. The records are 
made available for processing. On output, the 
error condition is ignored and the records are 
considered written correctly. 
SKIP 

No records in the error chain are made avail- 
able for processing. The next chain of records 
is read from the diskette, and processing con- 
tinues with the first record of that chain. On 
output, the SKIP option is the same as the 
IGNORE option, 
name 

IOCS branches to your error routine named by 
this parameter regardless of whether or not 
ERREXT=YES is specified. In this routine you 
can process or make note of the error condition 
as desired. 
If ERREXT is not specified, register 1 contains the 
address of the first record in the error chain. When 
processing in the ERROPT routine, reference records 
in the error chain by referring to the address sup- 
plied in register 1. The contents of the lOREG regis- 
ter or work area are variable and should not be used 



to process error records. Also, get macros must not 
be issued for records in the error chain. If any other 
IOCS macros (excluding eret if errext=yeS) are 
used in this routine, the contents of register 13 (with 
rdonly) and 14 must be saved and restored after 
their use. At the end of the routine, return control to 
IOCS by branching to the address in register 14. For 
a read error, IOCS skips that error chain of records, 
and makes the first record of the next chain avail- 
able for processing in the main program. 

If errext is specified, register 1 contains the 
address of a two part parameter list containing the 
4-byte dtfdu address and the 4-byte address of the 
first record in the error chain. Register 14 contains 
the return address. Processing is similar to that de- 
scribed above except for addressing the records in 
error. 

At the end of its processing, the routine returns to 
Liocs by issuing the ERET macro. 

For an input file, the program: 

• skips the error chain and reads the next chain 
with an ERET SKIP, 

• ignores the error with an ERET IGNORE, 

• it makes another attempt to read the error 
chain with an ERET retry. 

For an output file the only acceptable parameters 
are IGNORE or name, and the program 

• ignores the error condition with ERET IGNORE 
or ERET SKIP, 

• attempts to write the error chain with an ERET 
RETRY. Bad spot control records (1,2, 13, or 26 
records depending on the CMDCHN specifica- 
tion) are written at the current diskette address, 
and the write chain is retried in the next 1, 2, 
13, or 26 (depending on the CMDCHN specifica- 
tion) sectors on the disk. 

The DTFDU error options are shown in Figure 3-18. 



To Terminate the job, 


specify nothing; 


Skip the error record. 


specify ERROPT -SKIP; 


Ignore the error record, 


specify 

ERROPT = IGNORE, 


Process the error record, 


specify ERROPT = name; 


after processing the record, to leave the error-processing 
routine and 


Skip the (input) record. 


execute ERET SKIP; 


Ignore the record. 


execute ERET IGNORE; 


Retry reading or writing the re- 
cord. 


execute ERET RETRY. 



Figure 3-18. DTFDU error options. 

FEED= ( YES |NO): If YES is specified and IOCS 
detects an end-of-file condition, the diskette being 
processed is fed to the stacker and a new diskette is 
fed to the disk drive (providing another diskette is 
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still in the hopper). If NO is specified, the diskette is 
left mounted for the next job. If the operand is omit- 
ted, YES is assumed. 

FILESEC=YES: This operand applies to output 
only. On output it causes OPEN or OPENR to set the 
security flag in the file label. For subsequent input, 
the security flag causes an operator message to be 
written. The operator must then reply in order to 
make the file available to be read. 

Note: When this operand is used with WRTPROT=YES, the 
reuse of the diskette is prevented. 

IOAREAl=name: This operand specifies the sym- 
bolic name of the I/O area used by the file. IOCS 
either reads or writes records using this area. Note 
that you should provide an I/O area equal in size to 
the result obtained from multiplying the RECSIZE 
entry by the CMDCHN entry. 



save area. Each task should have its own uniquely 
defined save area. When an imperative macro 
(except OPEN, OPENR) is issued, register 13 must 
contain the address of the save area associated with 
the task. The fact that the save areas are unique for 
each task makes the module reentrant (that is, capa- 
ble of being used concurrently by several tasks). 

If an ERROPT routine issues I/O macros using the 
same read-only module that caused control to pass 
to the error routine, your problem program must 
provide another save area. One save area is used for 
the normal I/O operations, and the second for 
input/output operations in the ERROPT routine. 
Before returning to the module that entered the 
ERROPT routine, register 13 must be set to the save 
area address originally specified for that dtp. 

If this operand is omitted, the generated module 
is not reentrant and no save area need be estab- 
lished. 



IOAREA2=name: If two I/O areas are used by GET 
or PUT, this operand is specified. You should pro- 
vide an I/O area equal in size to the result obtained 
from multiplying the RECSiZE entry by the CMDCHN 
entry. 

IOREG=(r): This operand specifies the general 
purpose register (one of 2 to 12) in which iocs puts 
the address of the logical record that is available for 
processing. At OPEN or OPENR time, for output files, 
IOCS puts the address of the area where the user can 
build a record in this register. The same register can 
be used for two or more files in the same program, if 
desired. If this is done, the problem program must 
store the address suppUed by iocs for each record. 
If this operand is specified, omit the WORKA ope- 
rand. 

This operand must be specified if the CMDCHN 
factor is 2 or higher and records are processed in one 
I/O area, or if two I/O areas are used and records are 
processed in both I/O areas. 

MODNAME=name: This operand specifies the 
name of the logic module which is to process the file. 
If the logic module is assembled with the program, 
MODNAME must Specify the same name as the 
DUMODFx macro. If this operand is omitted, stan- 
dard names are generated for calling the logic mo- 
dule. If two DTP macros call for different functions 
that can be handled by a single module, only one 
module is called. 

RDONLY=YES: This operand is specified if the 
DTP is used with a read-only module. Each time a 
read-only module is entered, register 13 must con- 
tain the address of a 72-byte double-word aligned 



RECSIZE=nnn: This operand specifies (in bytes) 
the length of each record in the input/output area (1 
to 128 bytes). 

SEPASMB=YES: Include this operand only if the 
DTFDU is assembled separately. This causes a 
catalr card with the filename to be punched ahead 
of the object deck and the filename to be defined as 
an entry point in the assembly. If the operand is 
omitted, the assembler assumes that the DTP is being 
assembled with the problem program and no 
CATALR card is punched. 

TYPEFLE= (INPUT I OUTPUT) : This operand 
indicates whether the file is an input or output file. 

VERIFY=YES: This operand specifies that the 
input on a 3741/3742 must be verified before proc- 
essing may continue. If verify=yes is not specified, 
it is assumed that the input need not be verified. If 
VERIFY=YES is Specified and the input is not veri- 
fied, the job is canceled and message 4n57I is issued. 
If the operand is specified for an output file, it will 
be ignored. 

VOLSEQ=YES: This operand is only valid on 
input. If specified, it causes OPEN or openr to en- 
sure that the volume sequence numbers of a multi- 
volume file are in ascending and sequential order. 
However, if the volume sequence number of the first 
volume processed is blank, no volume sequence 
checking is done. 

WORKA=YES: If I/O records are processed or 
built in work areas instead of in the I/O areas, speci- 
fy this operand. You must set up the work area in 
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storage. The address of the work area, or a general WRTPROT=YES: This operand indicates that an 

register containing the address, must be specified in output file will be created with Write-Protect 

each GET or PUT macro. For a get or PUT macro, (meaning that the file cannot be overwritten). For 

IOCS moves the record to or from the specified work 3540 support, this has no effect on subsequent input 

area. processing of the file. 

When this operand is specified, the lOREG ope- Note: when this operand is used with FILESEC=YES, the reuse 

rand must be omitted. of the diskette is prevented. 
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DUMODFx Macro 

Two categories of file characteristics are defined for 
diskette unit module generation macros: 

• DUMODFI - Diskette Unit MODule, Fixed 
length records, Input file. 

• DUMODFO - Diskette Unit MODule, Fixed 
length records, Output file. 

The macro operation and the keyword operands 
define the characteristics of the module. 

A module name can be contained in the name 
field of this macro. The macro operation is con- 
tained in the operation field, either dumodfi (for 
input) or DUMODFO (for output). 

ERREXT=YES: Include this operand if perma- 
nent errors are returned to a problem program 
ERROPT routine or if the eret macro is used with 
the DTF and module. The ERROPT operand must be 
specified for this module. 

ERROPT=YES: This operand applies to both 
DUMODFX macros. This operand is included if the 
module handles any of the error options for an error 
chain. Logic is generated to handle any of the three 
options (IGNORE, SKIP, or name) regardless of which 
option is specified in the DTF. This module also 
processes any DTF in which the ERROPT operand is 
not specified. 

If this operand is not included, your program is 
canceled whenever a permanent error is encoun- 
tered. 

RDONLY=YES: This operand causes a read-only 
module to be generated. If this operand is specified, 
any DTF used with this module must have the same 
operand. 

SEPASMB=YES: Include this operand only if the 
logic module will be assembled separately. This 
causes a CATALR card with the module name 



(standard or user-specified) to be punched ahead of 
the object deck, and defines the module name to be 
defined as an ENTRY point in the assembly. If the 
operand is omitted, the assembler assumes that the 
logic module is being assembled with the problem 
program and no catalr is punched. 

Standard DUMOD Names 

Each name begins with a 3 -character prefix (UN) 
and continues with a 5 -character field corresponding 
to the options permitted in the generation of the 
module, as shown below. 

DUMODFx name = IJNabcde 



= D 

= I DUMODFI 

= O DUMODFO 

= C ERROPT=YES and ERREXT=YES 

= E ERROPT=YES 

= Z neither is specified 

= Z 

= Y RDONLY=YES 

= Z RDONLY not specified 



Subset/Superset DUMOD Names 

Figure 3-19 illustrates the subsetting and superset- 
ting allowed for DUMOD names. 



* + * * 

IJNDICZY 
E Z 
Z 



+ Subsetting/supersetting permitted. 
* No subsetting/supersetting permitted. 



Figure 3-19. Subsetting and supersetting of DUMOD names. 
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DTP IS Macro 

The DTFis macro defines a dasd file for the Indexed Sequential Access Method. 



Applies to 








Ran. 
Rtvl. 


Seq. 
Rtvl. 


Load 


Add 




X 


X 


X 


X 


M 


DSKXTNT=n 


Maximum number of extents specified for this file 


X 


X 


X 


X 


M 


IOROUT=xxxxxx 


(LOAD, ADD. RETRVE. or ADDRTR) 


X 


X 


X 


X 


M 


KEYLEN = nnn 


Number of bytes in record key (maximum is 255) 


X 


X 


X 


X 


M 


NRECDS=nnn 


Number of records in a block. Specify for blocked records 
only; if unblocked, 1 is assumed. 


X 


X 


X 


X 


M 


RECFORM = xxxxxx 


(FIXUNB or FIXBLK) 


X 


X 


X 


X 


M 


RECSIZE=nnnn 


Number of characters in logical record. 


X 


X 


X 


X 





CYLOFL=nn 


Number of tracks for each cylinder overflow area. Maxi- 
mum = 8 for 231 1 , 1 8 for 231 4 , 1 7 for 3330 and 3333, 
1 for 3340 


X 


X 


X 


X 





DEVICE=nnnn 


(231 1 , 2314, 3330, 3340). If omitted, 231 1 is assumed. 


X 


X 


X 


X 





ERREXT=YES 


Non data-transfer error returns and ERET desired. 


X 


X 


X 


X 





HINDEX=nnnn 


(231 1 , 2314, 3330, 3340). Unit containing highest level 
index. If omitted, 231 1 is assumed. 


X 


X 




X 





HOLD = YES 


Track hold function is desired 


X 






X 





INDAREA =xxxxxxxx 


Symbolic name of cylinder index area 


X 






X 





INDSKIP=YES 


Index skip feature is to be used 


X 






X 





INDSIZE=nnnnn 


Number of bytes required for the cylinder index area 






X 


X 





IOAREAL=xxxxxxxx 


Name of I/O area 


X 











10 ARE AR = xxxxxxxx 




X 









IOAREAS=xxxxxxxx 




X 


X 







I0AREA2 = xxxxxxxx 


Name of second I/O area 


X 


X 









IOREG=(nn) 


Register number. Omit if WORKA or WORKS is specified 








X 





IOSIZE = nnnn 


Bytes alloted to lOAREAL 


X 


X 









KEYARG =xxxxxxxx 


Name of key field in storage, for random retrieval or se- 
quential retrieval starting by key 


X 


X 


X 


X 





KEYLOC = nnnn 


Number of high-order position of key field within record, if 
RECFORM = FIXBLK 


X 


X 


X 


X 





MODNAME=xxxxxxxx 


Name of ISMOD logic module for this DTF. If omitted, IOCS 
generates standard name 


X 


X 


X 


X 





MSTiND=YES 


Master index used. 


X 


X 


X 


X 





RDONLY=YES 


Generates a read-only module. Requires a module save 
area for each task using the module. 


X 


X 


X 


X 





SEPASMB=YES 


DTFIS is to be assembled separately. 


X 


X 









TYPEFLE = xxxxxx 


(RANDOM, SEQNTL, or RANSEQ) 


X 


X 


X 


X 





VERIFY=YES 


Check disk records after they are written. 






X 


X 





WORKL = xxxxxxxx 


Name of work area for loading or adding to the file. 


X 











WORKR=xxxxxxxx 


Name of work area for random retrieval. Omit lOREG 




X 









WORKS = YES 


GET or PUT specifies work area 



M = Mandatory 
O=0ptional 

Figure 3-20. DTFIS macro. 

CYLOFL=n: This operand must be included if 
cylinder overflow areas are reserved for a file. Do 
not include this entry if no overflow areas are re- 
served. 



When a file is loaded or when records are added, 
this operand is required to reserve the areas for cyl- 
inder overflow. It specifies the number of tracks to 
be reserved on each cylinder. The maximum num- 
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ber of tracks that can be reserved on each cylinder 
is: 

for 2311 8 

for 2314, or 2319 18 

for 3330 or 3333 17 

for 3340 10 

DEVICE^ (2 3 11 123141333013340): This ope- 
rand specifies the unit that contains the prime data 
area or overflow areas for the logical file. For ISAM 
the prime data area must be on the same device 
type, and for a 3340 on the same model of data mo- 
dule. 

For devices supported by DOS/VSE and not in- 
cluded in the above operand specification, specify 
device codes as listed in Figure 3-21. 

DSKXTNT=n: This operand must be included to 
specify the maximum number of extents for this file. 
The number must include all the data area extents if 
more than one DASD area is used for the data re- 
cords, and aU the index area and independent over- 
flow area extents that are specified by EXTENT job 
control statements. Thus the minimum number 
specified by this entry is 2: one extent for one prime 

data area, and one for a cylinder index. Each area 
assigned to an ISAM file is considered an extent. 

Note: Master and cylinder indexes are treated as one area. When 
there is one master index extent, one cylinder index extent, and 
one prime data area extent, DSKXTNT=2 could be specified. 

ERREXT=YES: This operand is required for iocs 
to supply your program with detailed information 
about unrecoverable I/O errors occurring before a 
data transfer takes place, and for your program to be 
able to use the ERET imperative macro to return to 
IOCS specifying an action to be taken for an error 
condition. 

Some error information is available for testing by 
your program after each imperative macro is execut- 
ed, even if ERREXT=YES is not specified, by refer- 
encing fiQldJilenameC. Filename is the same name 
as that specified in the dtp header entry for the file. 
One or more of the bits in the filenamec byte may 



be set to 1 by iocs. The meaning of the bits varies 
depending on which parameter was specified in the 
lOROUT operand; Figure 3-22 shows the meaning if 
lOROUT=ADD, RETRVE, or ADDRTR was Specified; 
Figure 3-23 shows the meaning if iorout=load 
was specified. 

If ERREXT=YES is not Specified, iocs returns the 
address of the DTP table in register 1, as well as any 
data-transfer error information in filenamec, after 
each imperative macro is executed; non-data- 
transfer error information is not given. After testing 
filenamec, return to IOCS by issuing any imperative 
macro except eret; no special action is taken by 
IOCS to correct or check an error. 

If ERREXT=YES is Specified, IOCS returns the ad- 
dress of an ERREXT parameter list in register 1 after 
each imperative macro is executed, and information 
about both data-transfer and non-data-transfer er- 
rors in filenamec. The format of the errext par- 
ameter list is shown in Figure 3-25. After testing 
filenamec and finding an error, return to IOCS by 
using the eret imperative macro; iocs takes the 
action indicated by the eret operand. If hold=yes 
(and ERREXT=YES), ERET must be used to return to 
IOCS to free any held track. 

In your program, you should check byte 16, bit 7 
of the DTP for a blocksize compatibility error when 
adding to, or extending a file. If the blocksize of 
your program is not equal to the blocksize of the 
previously built file, this bit will be set to 1. 



HINDEX= (2311 |2314|3330|3340) : This entry 
specifies the unit containing the highest index. 

For devices supported by DOS/vSE and not in- 
cluded in the above operand specification, specify 
device codes as listed in Figure 3-24. 

Placing the highest index on a separate unit is 
recommended only if that unit is physically separate 
from the unit(s) holding the track indexes and the 
data of the file, and if it has its own access mecha- 
nism. 



DEVICE = 
specification 


Device in use 


2311 


2314 


2319 


3330-1,2* 


3340, 35MB 


3340, 70MB 


Default 


X 












2311 


X 












2314 




X 


x 








3330 








X 






3340 










x 


X 



* Also 3350 in 3330-1 compatibility mode. 
Figure 3-21. DEVICE= specifications for DTPIS. 
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Bit 


Cause 


Explanation 





DASD error 


An uncorrectable DASD error has occurred (except wrong length record). 


1 


Wrong length record 


A wrong length record has been detected during an I/O operation. 


2 


End of file 


The EOF condition has been encountered during execution of the sequential retrieval 
function. 


3 


No record found 


The record to be retrieved has not been found in the file. This applies to Random (RANSEQ) 
and to SETL in SEQNTL (RANSEQ) when KEY is specified, or after GKEY. 


t 


Illegal ID specified 


The ID specified to the SETL in SEQNTL (RANSEQ) is outside the prime file limits. 


5 


Duplicate record 


The record to be added to the file has a duplicate record kev of another record in the file. 


6 


Overflow area full 


An overflow area in a cylinder is full, and no independent overflow area has been specified; 
or an independent overflow area is full, and the addition cannot be made. You should assign 
an independent overflow area or extend the limit. 


7 


Overflow 


The record being processed in one of the retrieval functions (RANDOM /SEQNTL) is an 
overflow record. 



Figure 3-22. FilenameC - status or condition code byte if IOROUT=ADD, RETRVE, or ADDRTR 



Bit 


Cause 


Explanation 





DASD error 


An uncorrectable DASD error has occurred (except wrong length record). 


1 


Wrong length record 


A wrong length record has been detected during an I/O operation. 


2 


Prime area full 


The next to the last track of the prime data area has been filled during the load or extension 
of the file. You should issue the ENDFL macro, then do a load extend on the file with new 
extents given. 


3 


Cylinder index area full 


The cylinder index area is not large enough to contain all entries needed to index each 
cylinder specified for the prime data area. This condition can occur during the execution of 
the SETFL. You must extend the upper limit of the cylinder index by using a new extent 
card. 


4 


Master index full 


The master index area is not large enough to contain all the entries needed to index each 
track of the cylinder index. This condition can occur during SETFL. You must extend the 
upper limit, if you are creating the file, by using an extent card. Or, you must reorganize the 
file and assign a larger area. 


5 


Duplicate record 


The record being loaded is a duplicate of the previous record. 


6 


Sequence check 


The record being loaded is not in the sequential order required for loading. 


7 


Prime data area over- 
flow 


There is not enough space in the prime data area to write an EOF record. This condition can 
occur during the execution of the ENDFL macro. 



Figure 3-23. FilenameC - status or condition code byte if IOROUT=LOAD. 



HOLD=YES: This operand provides for the track 
hold option for both data and index records. If the 
HOLD operand is omitted, the track hold function is 
not performed. Because track hold cannot be per- 
formed on a LOAD file, hold=yes cannot be speci- 
fied when IOROUT=LOAD. 

If HOLD=YES and ERREXT=YES, your program 
must issue the eret macro to return to the ISAM 
module to free any held tracks. 

INDAREA=name: This operand specifies the 
name of the area assigned to the cylinder index. If 
specified, all or part of the cylinder index resides in 



virtual storage thereby increasing throughput. If this 
operand is included, INDSIZE must be included. 

If the area assigned to indarea is large enough 
for all the index entries to be read into virtual stor- 
age at one time and the index skip feature (indskip) 
is not specified, no presorting of records need be 
done. If the area assigned to indarea is not large 
enough, the records processed should be presorted to 
fully utilize the resident cylinder index. 

INDSKIP= YES: When cylinder index entries re- 
side in virtual storage, this operand specifies the 
index skip feature. This feature allows ISAM to skip 
any index entries preceding those needed to process 
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HINDEX = 
specification 


Device in use 


2311 


2314 


2319 


3330-1,2* 


3340,35MB 


3340,70MB 


Default 


X 












2311 


X 












2314 




X 


X 








3330 








X 






3340 










X 


X 



* Also 3350 in 3330-1 compatibility mode. 
Figure 3-24. HINDEX= specifications for DTFIS. 



Bytes 


Bits 


Contents 


0-3 


— 


DTP address 


4-7 


— 


Virtual storage address of the record in er- 
ror 


8-15 




DASD address (mbbcchhr) of the error 
where m is the extent sequence number 
and r is a record number which can be in- 
accurate if a read error occurred during a 
read of the highest level index. 


16 




Record identification: 




1 


Data record 




2 


Track index record 




3 


Cylinder index record 
Master index record 
Type of operation: 




4 


Not used 




5 


Not used 




6 


Read 




7 


Write 


17 


- 


Command code of failing CCW 



Figure 3-25. ERREXT parameter list. 

a given key. If the index skip operand is omitted, the 
cylinder indexes are processed sequentially. 

This operand may be specified only with the 
INDAREA and INDSIZE Operands and increases 
throughput only when: 

• The records are presorted. 

• The allocated virtual storage is insufficient for 
storing all of the cylinder index. 

• One or more large segments of the file are not 
referenced. 

INDSIZE=n: This operand specifies the length (in 
bytes) of the index area assigned in virtual storage to 
the cylinder index by indarea. The minimum you 
can specify is: 

n=(m+3)(keylength+6) 

where 

m = the number of entries to be read into virtual 

storage at a time. 
3 = the number of dummy entries 
6 = a pointer to the cylinder 



If m is set equal to the number of prime data 
cylinders+1, the entire cylinder index is read into 
virtual storage at one time. The maximum value for 
n = 32767. 

The resident index facility is suppressed if this 
operand is omitted, the minimum requirement is not 
met at assembly time, or an unrecoverable read er- 
ror is encountered while reading the index. 

IOAREAL=name: This operand must be included 
when a file is created (loaded) or when records are 
added to a file. It specifies the name of the output 
area used for loading or adding records to the file. 
The specified name must be the same as the name 
used in the DS instruction that reserves the area of 
storage. The ISAM routines construct the contents of 
this area and transfer records to DASD. 

This output area must be large enough to contain 
the count, key, and data areas of records. Further- 
more, the data-area portion must provide enough 
space for the sequence-link field of overflow records 
whenever records are added to a file (see Figure 
3-26). 

If lOAREAL is increased to permit the reading and 
writing of more than one physical record on DASD at 
a time, the lOSiZE operand must be included when 
records are added to the file. In this case, the 
lOREAL area must be at least as large as the number 
of bytes specified in the lOSiZE operand. 

When simultaneously building two ISAM files 
using two DTFs, do not use a common ioareal. 
Also, do not use a common area for ioareal, 
lOAREAR, and lOAREAS in multiple DTFs. 

IOAREAR=name: This operand must be included 
whenever records are processed in random order. It 
specifies the name of the input/output area for ran- 
dom retrieval (and updating). The specified name 
must be the same as that used in the DS instruction 
that reserves this area of storage. 

The I/O area must be large enough to contain the 
data area for records. Furthermore, the data-area 
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FUNCTION 


OUTPUT AREA REQUIREMENTS (IN BYTES) 


Count 


Key 


Sequence Link 


Data 


Load Unblocked Records 


8 


Key Length 


— 


Record Length 


Load Blocked Records 


8 


Key Length 


— 


Record Length x Blocking Factor 


Add Unblocked Records 


8 


Key Length 


10 


Record Length 


Add Blocked Records 


8 


Key Length 


— Record Length x Blocking Factor 
OR * 


8 


Key Lengtii 


10 Record Length 


* Whichever Is Largeir 



Figure 3-26. Output area requirements for loading or adding records to a file by ISAM. 



FUNCTION 


I/O AREA REQUIREMENTS (IN BYTES) 


Count 


Key 


Sequence Link 


Data 


Retrieve Unblocked Records 


— 


Key Length for sequential 
unblocked records 


10 


Record Length 


Retrieve Blocked Records 


— 






Record Length (including keys) x 
Blocking Factor 


— 




10 1 Record Length 


* Whichever Is Larger 





Figure 3-27. I/O area requirements for random or sequential retrieval by ISAM. 



portion must provide enough space for the 
sequence-hnk field of overflow records (see Figure 
3-27). 

IOAREAS=name: This operand must be included 
whenever records are processed in sequential order 
by key. It specifies the name of the input/output 
area used for sequential retrieval (and updating). 
The specified name must be the same as that used m 
the DS instruction that reserves this area of storage. 

This I/O area must be large enough to contain the 
key and data areas of unblocked records and the 
data area for blocked records. Furthermore, the 
data-area portion must provide enough space for the 
sequence-link field of overflow records (see Figure 
3-27). 

IOAREA2=name: This operand permits overlap- 
ping of I/O with indexed sequential processing for 
either the load (creation) or sequential retrieval 
functions. Specify the name of an I/O area to be 
used when loading or sequentially retrieving re- 
cords. The I/O area must be at least the length of the 
area specified by either the lOAREAL operand for the 
load function or the lOAREAS operand for the se- 
quential retrieval function. If the operand is omit- 



ted, one I/O area is assumed. If TYPEFLE=RANSEQ, 
this operand must not be specified. 

IOREG=(r): This operand must be included when- 
ever records are retrieved and processed directly in 
the I/O area. It specifies the register that ISAM uses 
to indicate which individual record is available for 
processing. ISAM puts the address of the current 
record in the designated register (any of 2 through 
12) each time a READ, write, get, or PUT is execut- 
ed. 

IOROUT= {LOAD!ADD|RETRVE|ADDRTR} : 

This entry must be included to specify the type of 
function to be performed. The parameters have the 
following meanings: 



LOAD 



ADD 



To build a logical file on a DASD or to extent a 
file beyond the highest record presently in a 
file. 

To insert new records into a file. 



RETRVE 

To retrieve records from a file for either ran- 
dom or sequential processing and/or updating 
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ADDRTR 

To both insert new records into a file (ADD) 
and retrieve records for processing and/or up- 
dating (RTR). 

IOSIZE=n: This operand specifies the (decimal) 
number of bytes in the virtual-storage area assigned 
for the add function using ioareal. The number n 
can be computed using the following formula: 

n = m(keylength-l-blocksize-l-40)+24 

where m is the maximum number of physical re- 
cords that can be read into virtual storage at one 
time; 40 is the sum of 8 for the count field and 32 for 
an ISAM CCW; 24 is another ISAM CCW. The number 
n must be at least equal to 

(keylength4-blocksize+74) 

This formula accounts for a needed sequence link 
field for unblocked records or short blocks (see Fig- 
ure 3-26 and Figure 3-27). 

If the operand is omitted, or if the minimum re- 
quirement is not met, no increase in throughput is 
reahzed. 

The number n should not exceed the track capac- 
ity because throughput cannot be increased by spec- 
ifying a number larger than the capacity of a track. 

KEYARG=name: This operand must be included 
for random read/write operations and sequential 
retrieval initiated by key. It specifies the symbolic 
name of the key field in which you must supply the 
record key to ISAM. 

KEYLEN=n: This operand must be included to 
specify the num^ber of bytes in the record key. 

KEYLOC=n: This operand must always be speci- 
fied if RECFORM=FlXBLK. It supplies ISAM with the 
high-order position of the key field within the data 
record. That is, if the key is recorded in positions 
21-25 of each record in the file, this operand should 
specify 21. 

ISAM uses this specification to locate (by key) a 
specified record within a block. The key area of a 
block of records contains the key of the highest re- 
cord in the block. To search for any other records, 
ISAM locates the proper block and then examines the 
key field within each record in the block. 

MODNAME=name: This operand may be used to 
specify the name of the logic module used with the 
DTP table to process the file. If the logic module is 
assembled with the program, the modname in the 
DTP must specify the same name as the ismod ma- 
cro. If this entry is omitted, standard names are 



generated for calling the logic module. If two DTP 
macros call for different functions that can be han- 
dled by a single module, only one module is called. 

MSTIND=YES: This operand is included when- 
ever a master index is used or is to be built for a file. 
The location of the master index is specified by an 
EXTENT job control statement. 

NRECDS=n: This operand specifies the number of 
logical records in a block (called the blocking fac- 
tor). It is required only if RECP0RM=PIXBLK. For 
PIXBLK, n must be >1; for pixunb, n must be =1. 

RDONLY=YES: This operand is specified if the 
DTP is used with a read-only module. Each time a 
read-only module is entered, register 13 must con- 
tain the address of a 72-byte doubleword-aligned 
save area. Each task should have its own uniquely 
defined save area. Register 13 must contain the ad- 
dress of the save area associated with the task each 
time an imperative macro (except OPEN, OPENR, 
LBRET, SETL, or SETPL) is issued. The fact that the 
save areas are unique for each task makes the mo- 
dule reentrant (that is, capable of being used concur- 
rently by several tasks). 

RECFORM= (FIXUNB|FIXBLK}: This operand 
specifies whether records are blocked or unblocked. 
PIXUNB is used for unblocked records, and pixblk 
for blocked records. If pixblk is specified, the key 
of the highest record in the block becomes the key 
for the block and must be recorded in the key area. 

The specification that is included when the logi- 
cal file is loaded onto a dasd must also be included 
whenever the file is processed. 

Records in the overflow area(s) are always un- 
blocked, but this has no effect on this operand. 
RECPORM refers to records in the prime data area 
only. 

RECSIZE=n: This operand must be included to 
specify the number of characters in the data area of 
each individual record. This operand should specify 
the same number for additions and retrieval as indi- 
cated when the file was created. 

SEPASMB=YES: Include this operand only if the 
DTFIS is assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and defines the filename as an 
ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the DTP is being 
assembled with the problem program and no 
CATALR card is punched. 
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TYPEFLE= {RANDOM|SEQNTL|RANSEQ} : 

This operand must be included when 
iOROUT=RETRVE OF iOROUT=ADDRTR. The Ope- 
rand specifies the type(s) of processing performed by 
your program for the file. 

RANDOM 

is used for random processing. Records are 
retrieved in random order specified by key. 

SEQNTL 

is used for sequential processing. Your pro- 
gram specifies the first record retrieved, and 
thereafter ISAM retrieves records in sequential 
order by key. The first record is specified by 
kev. ID. or the beginning of the logical file see 
"SETL Macro". 

RANSEQ 

is used if both random and sequential process- 
ing are to be performed for the same file. If 
RANSEQ is specified, the IOAREA2 operand 
must not be specified. 

TYPEFLE is not required for loading or adding 
functions. 

VERIFY=YES: Use this operand if you want to 
check the parity of disk records after they are writ- 
ten. If this operand is omitted, any records written 
on a disk are not verified. 

WORKL=name: This operand must be included 
whenever a file is created (loaded) or records are 
added to a file. It specifies the name of the work 
area in which you must supply the data records to 
ISAM for loading or adding to the file. The specified 
name must be the same as the name used in the DS 
instruction that reserves this area of storage. 

This work area must provide space for one logical 
record when a file is created (for blocked records: 
data; for unblocked records: key and data). 

The original contents of WORKL are changed due 
to record shifting in the ADD function. 



WORKR=name: When records are processed in 
random order, this operand must be included if the 
individual records are to be processed in a work area 
rather than in the I/O area. It specifies the name of 
the work area. This name must be the same as the 
name used in the DS instruction that reserves this 
area of storage. This area must provide space for 
one logical record (data area). When this entry is 
included and a READ (or WRITE) macro is executed, 
ISAM moves the individual record to (or from) this 
area. 



WORKS=YES: When records are processed in 
sequential order, this operand must be included if 
the individual records are processed in work areas 
rather than in the I/O area. Each GET and PUT ma- 
cro must specify the name of the work area to or 
from which ISAM is to move the record. When proc- 
essing unblocked records, the area must be large 
enough for one record (data area) and the record 
key (key area). For blocked records, the area must 
be large enough for one logical record (data area) 
only. The work area requirements are as shown in 
Figure 3-28. 





Unblocked 
Records 


Blocked Records 


Load 


(KL + DUorlO* 


DLorlO* 


ADD 


(KL + DDor 10* 


DLor(KL + 10)* 


Random Retrieve 


DL 


DL 


Sequential Re- 
trieve 


KL + DL 


DL 


K = KEY, D=Data, L=Length 
* Whichever is greater 



Figure 3-28. Work area requirements. 
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ISMOD Macro 



Operand 


Remarks 


ERREXT=YES' 


Required if non-data-transfer error con- 
ditions or ERET are desired. 


CORDATA=YES 


Required to add records using the DTF 
lOSIZE operand. 


C0RINDX=YES2 


Required to add or retrieve records with 
the cylinder index entries in virtual stor- 
age. 


HOLD=YES 


Specifies the track hold option. 


10AREA2=YES 


Required if two I/O areas are to be 
used. 


IOROUT= 
(LOADI 
ADD| 

RETRVE^I 
ADDRTR] 


Specifies function to be performed. 


RDONLY=YES' 


Required if a read-only module is to be 
generated. 


RECFORM = 
(FIXUNBI 
FIXBLKI 
BOTH'} 


Describes file. Required if lOROUT 
specifies ADD or ADDRTR. If lOROUT 
specifies LOAD or RETRVE, BOTH is 
assumed. 


RPS = SVA 


To assemble RPS logic modules. 


SEPASMB=YES 


If the module is assembled separately. 


TYPEFLE= 
(RANDOM 1 
SEQNTLI 
RANSEQ] 


Required if lOROUT specifies RETRV or 
ADDRTR. 



' Value assumed if 
^ Value assumed if 
RETRVE specified. 



RPS=SVA specified. 

RPS=SVA and IOROUTE=ADD or 



Figure 3-29. Operands of the ISMOD macro. 

Note: If an ISMOD module precedes an assembler language 
USING statement or follows your program, registers 2-12 remain 
unrestricted even at assembly time. However, if the ISMOD 
module lies within your program, you should issue the same 
USING statement (as that which was issued before the ISMOD 
module) directly following the module. This action is necessary 
because the ISMOD module uses registers 1, 2, and 3 as base 
registers, and the ISMOD CORD AT A module uses registers 1, 2, 
3, and 5 as base registers. Each time either module is assembled, 
these registers are dropped. 



CORINDX=YES: Include this operand to gener- 
ate a module that can process DTFIS files (add or 
random retrieve functions) with or without the cyl- 
inder index entries resident in virtual storage. If 
omitted, the module generated cannot process the 
resident cylinder index entries. 

If an unrecoverable I/O error occurs while read- 
ing indexes into virtual storage, the program will not 
use the resident cylinder index entries. 

CORD ATA= YES: Include this operand if the mo- 



dule is to add records to files with the lOSiZE dtfis 
operand. If this operand is included, the lOSiZE ope- 
rand is required in the DTF. If you omit the 
cordata=yes operand, you will not have an in- 
crease in throughput when adding records to a file. 

ERREXT=YES: Include this operand if the ERET 
macro is to be used with this module or if non-data- 
transfer error conditions are returned in filenamec. 
If HOLD=YES and errext=yes, your program must 
issue the ERET macro to return to the ISAM module 
to free any held tracks. See the DTF errext and 
HOLD operands. 

HOLD=YES: This operand provides for the track 
hold option for both data and index records. If the 
HOLD operand is omitted, the track hold function is 
not performed. 

Because track hold cannot be performed on a 
LOAD file, HOLD=YES cannot be specified when 

IOROUT=LOAD. 

If HOLD=YES and ERREXT=YES, your program 
must issue the eret macro to return to the ISAM 
module to free any held tracks. 

IOAREA2=YES: Include this operand if a second 
I/O area is to be used - that is, if ioarea2 is speci- 
fied in any of the DTFs linked to the logic module. 
The operand is only valid for load or sequential 
retrieval functions. The module can process DTFs 
with one or two I/O areas specified. This operand 
must not be specified if typefle=ranseq is speci- 
fied. 

IOROUT= {LOADlADD|RETRVE| ADDRTR} : 

This operand specifies the type of module required 
to perform a given function. 



LOAD 



generates a module for creating or extending a 
file. 

ADD 

generates a module for adding new records to 
an existing file. 

RETRVE 

generates a module to retrieve, either random- 
ly or sequentially, records from a file. 

ADDRTR 

generates a module that combines the features 
of the ADD and RETRVE modules. This module 
also processes any file in which only add or 
RETRVE is specified in the lOROUT operand of 
the DTF, and in which the typefle operand 
contains the corresponding parameter (or a 
subset of it). 
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RDONLY=YES: This operand causes a read-only 
module to be generated. Whenever this operand is 
specified, any DTF used with the module must have 
the same operand. 

RECFORM= (FIXUNB|FIXBLK|BOTH} : This 
operand generates a module that creates, adds to, or 
processes an unblocked (FIXUNB) or blocked 
(FIXBLK) file. If BOTH is Specified, a module is gen- 
erated to process both unblocked and blocked files, 
and the DTP may specify either fixunb or FiXBLK in 
the RECFORM operand. The RECFORM operand is 
required only when lOROUT specifies add or 
ADDRTR. If lOROUT Specifies load or retrve, a 
module that handles fixed-length blocked and un- 
blocked files is generated, and the operand is not 
required. 

RPS=SVA This operand causes the RPS logic mo- 
dules to be assembled. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and defines the module name as an ENTRY 
point in the assembly. If the operand is omitted, the 
assembler assumes that the module is being assem- 
bled with the DTF and the problem program and no 
CATALR card is punched. 

TYPEFLE= {RANDOM|SEQNTL|RANSEQ} : 

This operand is required when lOROUT specifies 
RETRVE or ADDRTR. RANDOM generates a module 
that includes only random retrieval capabilities. 
SEQNTL generates a module that includes only se- 
quential retrieval capabilities, ranseq generates a 
module that includes random and sequential capa- 
bilities. It also processes any file in which the 
TYPEFLE operand specifies either RANDOM or 

SEQNTL. If TYPEFLE=RANSEQ, IOAREA2=YES must 

not be specified. 

When all operands are omitted, the ISMOD mo- 
dule can only process files where iorout=retrve, 

TYPEFLE=RANSEQ, CORINDX, CORDATA, HOLD, and 

RDONLY are not specified. The name of that module 
is IJHZRBZZ. 

Standard ISMOD Names 

Each name begins with a 3-character prefix (IJH) 
and continues with a 5 -character field corresponding 
to the options permitted in the generation of the 
module. 

ISMOD name = IJHabcde 
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a = A RECFORM=BOTH, IOROUT= ADD or ADDRTR 

= B RECFORM=FIXBLK, IOROUT=ADD or 
ADDRTR 

= U RECFORM=FIXUNB, IOROUT=ADD or 
ADDRTR 

= Z RECFORM is not specified. (IOROUT=LOAD or 
RETRVE) 

b = A IOROUT=ADDRTR 

= I IOROUT=ADD 

= L IOROUT=LOAD 

= R IOROUT=RETRVE 

= V IOROUT=ADDRTR, RPS=SVA 

= X IOROUT=LOAD, RPS=SVA 

c = B TYPEFLE=RANSEQ 

= G I0AREA2=YES, TYPEFLE=SEQNTL or 
IOROUT=LOAD 

= R TYPEFLE=RANDOM 

= S TYPEFLE=SEQNTL 

= Z neither is specified (IOROUT=LOAD or ADD) 

d = B CORINDX=YES and HOLD=YES 

= C CORINDX=YES 

= O HOLD=YES 

= Z neither is specified 

e = F CORDATA=YES, ERREXT=YES, RDONLY=YES 
= G CORDATA=YES and ERREXT=YES 
= O CORDATA=YES and RDONLY=YES 
= P CORDATA=YES 
= S ERREXT=YES and RDONLY=YES 
= T ERREXT=YES 
= Y RDONLY=YES 
= Z neither is specified 

Subset/Superset ISMOD Names 

Figure 3-30 shows the subsetting and supersetting 
allowed for ISMOD names. Five parameters allow 
supersetting. For example, the module IJHBABZZ is 
a superset of the module IJHBASZZ. 



+ + + 


+ + 


I J H A A B 


B F 


B I R 





Z + + 


+ + 


+ A B 


C S 


A R S 


Z Y 


U * + 


+ 


Z L G 


G 


S 


P 


+ 


+ 


G 


T 


Z 


Z 


+ Subsetting/supersetting permitted. 


* No subsetting/supersetting permitted. 



Figure 3-30. Subsetting and supersetting of ISMOD names. 

If two or more modules with the same entry point 
are included, the hnkage editor message 21431, 



(invalid duplication of entry point label) is generat- 1 . Specify prime data in core for each ADD type 

ed. (Occasionally these entry points are not obvious DTF in your program. In this case, superset mo- 

when using the preceding chart, but the module can dules are generated. 

perform the indicated functions.) This message can 2. Specify the modname operand in the DTF, and 

usually be supressed by including a superset mo- include an ISMOD of that name. The DTP then 

dule. However, modules with and without prime generates only the specified module. 

data in main storage or modules with 

TYPEFLE=RANDOM and I0AREA2=YES cannot be 

combined. Therefore, you should take either of the 

following actions: 
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DTFMR Macro 

DTFMR defines an input file processed on a 1255, 1259, or 1419 magnetic character reader, or a 1270 or 1275 
optical character reader/sorter. 



M 


DEVADDR = SYSnnn 


Symbolic unit assigned to the magnetic character reader. 


M 


IOAREA1 = xxxxxxxx 


Name of the document buffer area. 





ADDAREA=nnn 


Additional document buffer area (ADDAREA+RECSIZE = 250). If omitted, no area is 





ADDRESS =DUAL 


Must be included only if the device is a 1 41 9 or 1 275 with a dual address adapter. 





BUFFERS=nnn 


Specifies the number of buffers needed. If omitted, 25 is assumed. 


O 


ERROPT = xxxxxxxx 


Name of your error routine. Required only if the CHECK macro is used. 





EXTADDR = xxxxxxxx 


Name of your stacker selection routine. Required only if SORTMDE=ON. 





ir\Dc:r:i_/«r,\ 


Fointer register number, if omitted, register 2 is assumed. General registers 2-12, 
written in parentheses. 





MODNAME=xxxxxxxx 


Name of your I/O module. Required only if a nonstandard module is referenced. 





RECSIZE=nnn 


Specifies the maximum record length. If omitted, 80 is assumed. 





SECADDR=SYSnnn 


Specifies secondary symbolic unit assigned to (dual address) 1 275 or 1 41 9. Required 
only if LITE macro is used. 


O 


SEPASMB=YES 


Required only if the DTF is assembled separately; otherwise it should be omitted. 





SORTMDE = xxx 


ON - 1255/1259/1270 or program sort mode used; OFF - 1419/1275 sort mode used. 
If omitted, ON is assumed. 



M = Mandatory 
0= Optional 

Figure 3-3 1 . DTFMR macro operands. 

ADDAREA=n: This operand must be included 
only if an additional bufTer work area is needed. 
The parameter n specifies the number of additional 
bytes you desire in each buffer. The sum of the 
ADDAREA and RECSIZE specifications must not ex- 
ceed 250. This area can be used as a work area 
and/or output area and is reset to binary zeros when 
the next GET or READ for the file is executed. 

ADDRESS=DUAL: This operand must be includ- 
ed only if the 1419 or 1275 contains the dual address 
adapter. If the single address adapter is used, this 
operand must be omitted. 

BUFFERS= (15 |n} : This operand is included to 
specify the number of buffers in the document buff- 
er area. The limits for n are 12 and 254. 25 is as- 
sumed if this operand is omitted. 

DEVADDR=SYSnnn: This operand is required 
and specifies the symbolic unit to be associated with 
the file. The symbolic unit represents an actual I/O 
device address used in the assgn job control state- 
ment to assign the actual I/O device address to the 
file. 

ERROPT=name: This operand may be included 
only if the CHECK macro is used. The name parame- 
ter specifies the name of the routine that the CHECK 



macro branches to if any error condition is posted in 
byte 0, bits 2 to 4 (and bit 5, if no control address is 
specified in the CHECK macro) of the buffer status 
indicators. It is your responsibility to exit from this 
routine (see the "check Macro".) 

EXTADDR=name: This operand specifies the 
name of your stacker selection routine to which con- 
trol is given when an external interrupt is encoun- 
tered while reading and sorting the documents inter- 
nally. This operand may be omitted only when you 

specify SORTMDE=OFF. 

IOAREAl=name: This operand is required and 
specifies the name of the document buffer area that 
will be used by the file. Figure 4-3 shows the format 
of the document buffer area. 

IOREG= {(2)|(r)} : This operand specifies the 
general-purpose register (one of 2 to 12) that the 
IOCS routines and your routines use to indicate 
which individual document buffer is available for 
processing, iocs puts the address of the current doc- 
ument buffer in the specified register each time a 
GET or READ is issued. Register 2 is assumed if this 
operand is omitted. 

The same register may be specified in the lOREG 
entry for two or more files in the same program, if 
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desired. In this case, your program may need to 
store the address supplied by IOCS for each record. 

MODNAME=name: This operand specifies the 
name of the logic module generated by MRMOD. If 
the operand is omitted, IOCS generates the standard 
system module name. 

RECSIZE= (80 In} : This operand specifies the 
actual length of the data portion of the buffer. The 
record size specified must be the size of the largest 
record processed. If this operand is omitted, a re- 
cord size of 80 is assumed. The sum of the 
ADD AREA and RECSIZE specifications must not ex- 
ceed 250. 

SECADDR=SYSnnn: This operand specifies the 
symbolic unit to be associated with the secondary 
control unit address if the 1419 or 1275 with the dual 
address adapter and LITE macro are utilized. The 
operand should be omitted if the pocket LITE macro 
is not being used. 

SEPASMB=YES: Include this operand only if the 
DTFMR is assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and defines the filename as an 
ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the DTP is being 
assembled with the problem program and no 
CATALR card is punched. 

SORTMDE= (ONjOFF) : This operand specifies 
the method of sorting done on the 1419. 
SORTMDE=ON indicates that the program sort mode 
is being used. SORTMDE=OFF indicates that sorting 



is under control of the magnetic character reader. If 
the operand is omitted, the program sort mode is 
assumed. 

MRMOD Macro 

The first card contains MRMOD in the operation field 
and may contain a module name in the name field. 
If a module name is omitted, the following standard 
module name is generated by IOCS: 

IJU (S|ZZZZ 

Dj 

(S = single address adapter, and D = dual address 
adapter). 

The operands you can specify for MRMOD are 
discussed below. 

ADDRESS= (SINGLE IDUAL) : Required only if 
the dual address adapter is used for the 1419 or 
1275. If the operand is omitted, the single address 
adapter is assumed by the assembler. 

BUFFERS=nnn: A numeric value (nnn) equal to 
the corresponding value specified in the DTFMR 
macro. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and the module name to be defined as an 
ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the module is 
being assembled with the DTF and the problem pro- 
gram and no CATALR card is punched. 
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DTFMT Macro 

A DTFMT macro is included for each EBCDIC or ASCII magnetic tape input or output file that is to be processed. 



Applies to 






h 


Input 


Output 


Work 




X 


X 


X 


M 


BLKSIZE = nnnnn 


Length of one I/O area in bytes (maximum = 32,767). 


X 


X 


X 


M 


DEVADDR=SYSxxx 


Symbolic unit for tape drive used for this file. 


X 




X 


M 


EOFADDR =xxxxxxxx 


Name of your end-ot-file routine. 


X 


X 


X 


M 


FILABL = xxxx 


(NO, STD, or NSTD). If NSTD specified, include LABADDR. If 
omitted, NO is assumed. 


X 


X 




M 


I0AREA1 =xxxxxxxx 


Name of first I/O area. 


X 


X 







ASCII=YES 


ASCII file processing is required. 


X 


X 




O 


BlJFOFF=nn 


Length of block prefix if ASCII = YES. 


X 









CKPTREC=YES 


Checkpoint records are interspersed with input data records. 
IOCS bypasses checkpoint records. 


X 


X 


X 





ERREXT=YES 


Additional errors and ERET are desired. 


X 


X 


X 





ERROPT = xxxxxxxx 


(IGNORE, SKIP, or name of error routine). Prevents job termi- 
nation on error records. 


X 


X 


X 





HDRINFO=YES 


Print header label information if FILABL=STD. 


X 


X 







IOAREA2 = xxxxxxxx 


If two I/O areas are used, the name of the second area. 


X 


X 







IOREG=(nn) 


Register number. Use only if GET or PUT does not specify a 
work area or if two I/O areas are used. Omit WORKA. General 
registers 2-1 2, written in parentheses. 


X 


X 







LABADDR = xxxxxxxx 


Name of your label routine if FILABL=NSTD, or if 
FILABL=STD and user-standard labels are processed. 


X 









LENCHK=YES 


Length check of physical records if ASCII=YES and 
BUFOFF=4. 


X 


X 


X 





MODN AME = xxxxxxxx 


Name of MTMOD logic module for this DTF. If omitted, IOCS 
generates standard name. 






X 





NOTEPNT = xxxxxx 


(YES or POINTS). YES if NOTE, POINTW, POINTR, or POINTS 
macro used. POINTS if only POINTS macro used. 


X 


X 


X 





RDONLY=YES 


Generate read-only module. Requires a module save area for 
each task using the module. 


X 




X 





READ = xxxxxxx 


(FORWARD or BACK). If omitted, FORWARD assumed. 


X 


X 


X 





RECFORM=xxxxxx 


(FIXUNB, FIXBLK, VARUNB, VARBLK, SPNUNB, SPNBLK, or 
UNDEF). For work files use FIXUNB or UNDEF. If omitted, 
FIXUNB is assumed. 


X 


X 







RECS!ZE = nnnn 


If RECFORM = FIXBLK, number of characters in record. If 
RECFORM = UNDEF, general registers 2-12, written in par- 
entheses. Not required for other records. 


X 


X 


X 





REWIND = xxxxxx 


(UNLOAD or NORWD). Unload on CLOSE or end-of-volume, or 
prevent rewinding. If omitted, rewind only. 


X 


X 


X 





SEPASMB=YES 


DTFMT is to be assembled separately. 




X 




o 


TPMARK= (YES|NO} 


Causes IOCS to write or to omit a tapemark ahead of data 
records if FILABL=NSTD or NO is specified. 


X 


X 


X 





TYPEFLE=xxxxxx 


(INPUT, OUTPUT, or WORK). If omitted, INPUT is assumed. 




X 







VARBLD=(nn) 


Register number, if RECFORM = VARBLK and records are build 
in the output area. General registers 2-12, written in par- 
entheses. 


X 









WLRERR = xxxxxxxx 


Name of wrong-length-record routine. 


X 


X 







WORKA=YES 


GET or PUT specifies work area. Omit lOREG. 



M = Mandatory 
= Optional 

Figure 3-32. DTFMT Macro Operands. 
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ASCII=YES: This operand specifies that process- 
ing of ASCII tapes is required. If this operand is 
omitted, EBCDIC processing is assumed. ASCII = YES 
is not permitted for work files. 

BLKSIZE=nnnnii: Enter the length of the I/O area. 
If the record format is variable or undefined, enter 
the length of the largest block of records. If a read 
or WRITE macro specifies a length greater than n for 
work files, the record to be read or written will be 
truncated to fit in the I/O area. The maximum block 
size is 32,767 bytes. The minimum size of a physical 
tape record (gap to gap) is 12 bytes. A record of 
eleven bytes or less is treated as noise. 

For output processing of variable records, the 
minimum physical record length is 18 bytes. If less 
than 1 8 bytes are specified for variable blocked or 
variable unblocked records, BLKSIZE=18 is assumed. 

For output processing of spanned records, the 
minimum physical record length is 1 8 bytes. If 
SPNBLK or SPNUNB and TYPEFLE=OUTPUT are speci- 
fied in the DTFMT and the blksize is invalid or less 
than 18 bytes, an mnote is generated and 
BLKSIZE=18 is assumed. 

For ASCII tapes, the BLKSIZE includes the length 
of any block prefix or padding characters present. If 
ASCll=YES and blksize is less than 18 bytes (for 
fixed-length records only) or greater than 2048 
bytes, an MNOTE is generated because this length 
violates the Umits specified by American National 
Standards Institute, Inc. 

BUFOFF= {0|n}: This operand indicates the 
length of the block prefix. Enter the length of the 
block prefix if processing of the block prefix is re- 
quired. This operand can only be included when 
ASCII=YES is specified. The contents of this field are 
not passed on to you. 

n can have the following values: 

Value Condition 

0-99 If TYPEFLE = INPUT 

IF TYPEFLE = OUTPUT 

4 If TYPEFLE= OUTPUT and RECFORM = VARUNB or 

VARBLK. In this case, the program automatically 
inserts the physical record length in the block 
prefix. 

CKPTREC=YES: This operand is necessary if an 
input tape has checkpoint records interspersed 
among the data records, iocs bypasses any check- 
point records encountered. This operand must not 
be included when ASCII=YES. 

DEVADDR= {SYSRDR|SYSIPT|SYSPCH| 
SYSnnnjSYSLST): 



This operand specifies the symbolic unit to be asso- 
ciated with the file. An ASSGN job control statement 
assigns an actual channel and unit number to the 
unit. The ASSGN job control statement contains the 
same symbolic name as devaddr. When processing 
ASCII tapes, you must specify a programmer logical 
unit (SYSnnn). 

EOFADDR=name: This operand specifies the 
name of your end-of-file routine, iocs automatical- 
ly branches to this routine on an end-of-file condi- 
tion. This entry must be specified for input and 
work files. 

In your routine, you can perform any operations 
required for the end of file (generally you issue the 
CLOSE macro for the file), iocs detects end-of-file 
conditions in magnetic tape input by reading a tape- 
mark and EOF when standard labels are specified. If 
standard labels are not specified, IOCS assumes an 
end-of-file condition when the tapemark is read, if 
the unit is assigned to SYSRDR or sysipt when a /* 
is read. You must determine, in your routine, that 
this actually is the end of the file. 

ERREXT=YES: This operand enables your 
ERROPT or WLRERR routine to return to MTMOD by 
means of the eret (error return) macro. It also ena- 
bles nonrecoverable I/O errors occurring before data 
transfer takes place to be indicated to your program. 
To take full advantage of this option, the 
ERROPT =name operand must be specified. 

ERROPT= {IGNORE|SKIP|name} : This ope- 
rand specifies functions to be performed when an 
error block is encountered. Either IGNORE, skip, or 
the symbolic name of an error routine can be speci- 
fied. The functions of these specifications are: 

IGNORE 

The error condition is completely ignored, and 
the records are made available for processing. 
When reading spanned records, the entire 
spanned record or a block of spanned records 
is returned to the user rather than just the one 
physical record in which the error occurred. 

On output, the error is ignored and the physi- 
cal record containing the error is treated as a 
valid record. The remainder, if any, of the 
spanned record segments are written, if possi- 
ble. 



SKIP 



No records in the error block are made avail- 
able for processing. The next block is read 
from tape, and processing continues with the 
first record of that block. The error block is 
included in the block count. When reading 
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name 



spanned records, the entire spanned record or 
a block of spanned records is skipped rather 
than just one physical record. 

On output, the error is ignored and the physi- 
cal record containing the error is treated as a 
valid record. The remainder, if any, of the 
spanned record segments are written. 

IOCS branches to your error routine named by 
this parameter regardless of whether 
ERREXT=YES is Specified. In this routine, you 
can process or make note of the error condition 
as desired. 

The ERROPT operand applies to wrong-length 
records if the WLRERR operand is not included. If 
both ERROPT and WLRERR are omitted and wrong- 
length records occur, IOCS assumes the ignore op- 
tion. 

Note: For ASCII tapes, the pointer to the block in error indicates 
the first logical record following the block prefix. 

FILABL= (NO|STD|NSTD) : This operand speci- 
fies what type of labels are to be processed. STD 
indicates standard labels, no indicates no labels, and 
NSTD indicates nonstandard labels. You must fur- 
nish a routine to check or create the nonstandard 
labels by using your own I/O area and an EXCP ma- 
cro to read or write the labels. The entry point of 
this routine is the operand of labaddr. 

The specification filabl=nstd is not permitted 
for ASCII files (that is, when ASCII=YES). Labels and 
tape data are assumed to be in the same mode. 

HDRINFO=YES: This operand, if specified with 
FILABL=STD, causes IOCS to print standard header 
label information (fields 3-10) on SYSLOG each time 
a file with standard labels is opened. It also prints 
the filename, logical unit, and device address each 
time an end-of-volume condition is detected. Both 
FILABL=STD and HDRINF0=YES must be specified 
for header label information to be printed. 

IOAREAl=name: This operand specifies the name 
of the I/O area. When variable-length records are 
processed, the size of the I/O area must include four 
bytes for the block size. This operand does not ap- 
ply to work files. 

IOAREA2=name: This operand specifies the name 
of a second I/O area. When variable-length records 
are processed, the size of the I/O area must include 
four bytes for the blocksize. This operand does not 
apply to work files. 



IOREG=(r): This operand specifies the register in 
which IOCS places the address of the logical record 
that is available for processing if: 

• two input or output areas are used. 

• blocked input or output records are processed 
in the I/O area. 

• variable unblocked records are read. 

• undefined records are read backwards. 

• neither bufoff=o nor worka=yes is specified 
for ASCII files. 

For output files, iocs places, in the specified reg- 
ister, the address of the area where you can build a 
record. Any of registers 2 to 12 may be specified. 

This operand cannot be used if worka=yes. 

LABADDR=name: Enter the symbolic name of 
your routine to process user-standard or nonstan- 
dard labels. 

For ASCII tapes, this operand may be used only 
for writing and checking user standard labels that 
conform to American National Standards Institute, 
Inc., standards. You must process these labels in 
EBCDIC. Nonstandard user labels are not permitted. 

LENCHK=YPS: This operand applies only to 
ASCII tape input if bufoff=4 and 
recform=varunb or varblk. It must be included 
if the block length (specified in the block prefix) is 
to be checked against the physical record length. If 
the two lengths do not match, the action taken is the 
same as described under the WLRERR operand, but 
the WLR bit (byte 5, bit 1) in the dtf is not set. 

MODNAME=name: This operand specifies the 
name of the logic module used with the DTF table to 
process the file. If the logic module is assembled 
with the program, this operand must specify the 
same name as the modname operand of the MTMOD 
macro. If this operand is omitted, standard names 
are generated for calling the logic module. If two 
DTF macros call for different functions that can be 
handled by a single module, only one module is 
called. For example, if one DTF specifies 
READ=FORWARD and another specifies 
READ=BACK, only one logic module capable of han- 
dling both functions is called. 

NOTEPNT= (POINTSI YES} : If the parameter 
YES is specified, the NOTE, POINTW, pointr, or 
POINTS macros can be issued for a tape work file. If 
POINTS is specified, only points macros can be is- 
sued for tape work files. The notepnt operand 
must not be specified for ASCII tape files because 
ASCII work files are not supported by DOS/VSE. 
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RDONLY=YES: This operand is specified if the 
DTF is used with a read-only module. 

READ= (FORWARD I BACK] : This operand speci- 
fies the direction in which the tape is read. If 
READ=BACK is specified and a wrong-length record 
smaller than the I/O area is encountered, the record 
is read into the I/O area right-justified. 

RECFORM= (FIXUNB |FIXBLK|VARUNB| 
VARBLK|SPNBLK|SPNUNB| 
UNDEF) : 

This operand specifies the type of EBCDIC or ASCII 
records in the input or output file. Enter one of the 
following parameters: 

FIXUNB For fixed-length unblocked records 

FIXBLK For fixed-length blocked records 

VARUNB For variable-length unblocked records 

VARBLK For variable-length blocked records 

SPNBLK For spanned variable-length blocked records 

(EBCDIC only) 

SPNUNB For spanned variable-length unblocked records 

(EBCDIC only) 
UNDEF For undefined records 

Work files may use only fixunb or undef. 

RECSIZE= (n|(r)} For fixed-length blocked re- 
cords, RECSIZE is required. It specifies the number 
of characters in each record. 

When processing spanned records, you must 
specify RECSiZE=(r) where r is a register that 
tains the length of each record. 

For undefined records, this entry is required for 
output files but is optional for input files. It specifies 
a general register (any of 2 to 12) that contains the 
length of the record. On output, you must load the 
length of each record into the register before you 
issue a PUT macro. Spanned-record output requires 
a minimum record length of 18 bytes. A physical 
record less than 1 8 bytes is padded with binary zeros 
to complete the 1 8-byte requirement. This applies to 
both blocked and unblocked records. If specified for 
input, IOCS provides the length of the record trans- 
ferred to virtual storage. 

REWIND= (UNLOADINORWD): If this specifi- 
cation is not included, tapes are automatically re- 
wound to load point, but not unloaded, on an OPEN 
or OPENR or a CLOSE or CLOSER macro or on an 
end-of- volume condition. If other operations are 
desired for a tape input or output file, specify: 

UNLOAD 

to rewind the tape on an OPEN (or OPENR) and 
to rewind and unload on a CLOSE (or CLOSER) 
or on an end-of-volume condition. 



con- 



NORWD 

to prevent rewinding the tape at any time. 
This option positions the read/write head be- 
tween the two tapemarks that indicate the end- 
of-flle condition. 

SEPASMB=YES: Include this operand only if the 
DTFMT is assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and the filename to be defined as 
an ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the dtf is being 
assembled with the problem program and no 
CATALR card is punched. 

TPMARK= {YES|NO} : A tapemark is normally 
written for an output file if nonstandard labels are 
specified (filabl=nstd). If no tapemark is desired, 
TPMARK=NO should be specified. If tpmark=no is 
specified together with filabl=std, the former 
specification is ignored. If FlLABL=NO is specified or 
the FILABL operand is omitted, tpmark=yes must 
be specified for iocs to write a tapemark ahead of 
the first data record. 

TYPEFLE= (INPUT IOUTPUTI WORK) : Use 
this operand to indicate whether the file is used for 
input or output. If input is specified, the GET macro 
is used. If OUTPUT is specified, the PUT macro is 
used. If WORK is specified, the read/write, 
NOTE/POlNTx, and CHECK macros are used. 

The specification of WORK in this operand is not 
permitted for ASCII files. 

VARBLD=(r): This entry is required whenever 
variable-length blocked records are built directly in 
the output area (no work area is specified). It speci- 
fies the number (r) of a general-purpose register 
(any of 2 to 12) that always contains the length of 
the available space remaining in the output area. 

IOCS calculates the space still available in the 
output area, and suppUes it to you in the varbld 
register after the PUT macro is issued for a variable- 
length record. You can then compare the length of 
the next variable-length record with the available 
space to determine whether the record will fit in the 
remaining area. This check must be made before the 
record is built. If the record does not fit, issue a 
TRUNC macro to transfer the completed block of 
records to the tape. The current record is then built 
as the first record of the next block. 

WLRERR=name: This operand applies only to 
tape input files. It specifies the name of your routine 
to receive control if a wrong-length record is read. If 
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the WLRERR entry is omitted but a wrong-length 
record is detected by IOCS, one of the following con- 
ditions results: 

• If the ERROPT entry is included for this file, the 
wrong-length record is treated as an error 
block, and handled according to your specifica- 
tions for an error (ignore, skip, or name of 
error routine). 

• If the ERROPT entry is not included, IOCS as- 
sumes the IGNORE option of ERROPT. 



WORKA=YES: If I/O records are processed in 
work areas instead of in the I/O areas, specify this 
operand. You must set up the work areas in virtual 
storage. The symbolic address of the work area, or a 
general-purpose register containing the address, 
must be specified in each GET or PUT. Omit IOREG 
if this operand is included. WORKA=yes is required 
for spanned record processing. 
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MTMOD Macro 

Listed here are the operands you can specify for 
MTMOD. The first card contains MTMOD in the oper- 
ation field and may contain a module name in the 
name field. 

ASCII=YES: Include the operand if processing 
ASCII input or output files is required. This entry is 
not permitted for work files. If omitted, EBCDIC file 
processing is assumed. 

CKPTREC=YES: Include this operand if input 
tapes processed by the module contain checkpoint 
records interspersed among the data records. The 
module also processes tapes that do not have check- 
point records; that is, those whose DTFs do not speci- 
fy CKPTREC=YES. 

This entry is not needed for work files, and is not 
valid for ASCII files. 

ERREXT=YES: Include this operand if additional 
I/O errors are to be indicated and/or the ERET ma- 
cro is used with this DTP and module. ERROPT=YES 
should be specified in this module for work files, but 
is not needed for input or output files. 

ERROPT=YES: Include this operand if the mo- 
dule is to handle any of the error options for an er- 
ror block. Code is generated to handle any of the 
three options (IGNORE, SKIP, or name). The module 
also processes any files in which the ERROPT ope- 
rand is not specified in the DTP. This entry is needed 
for work files, but it is not needed for input or out- 
put files. 

NOTEPNT= (YES|POINTS}: This operand ap- 
plies only to work files (EBCDIC only). 

Include this operand if NOTE/POiNTx logic is used 
with the module. If YES is specified, the module 
processes any NOTE, POINTR, POINTW, or POINTS 
macro. If POINTS is specified, only the POINTS ma- 
cro is processed. 

Modules specifying either one of the two options 
also process work files for which the NOTE/pointx 
operand is not specified in the dtp. Modules speci- 
fying YES also process work files specifying only 

POINTS. 

RDONLY=YES: This operand causes a read-only 
module to be generated. Whenever this operand is 
specified, any DTP used with the module must have 
the same operand. 

Each time a read-only module is entered, register 
13 must contain the address of a 72-byte 
doubleword-ahgned save area. Each task should 



have its own uniquely defined save area and each 
time an imperative macro (except an OPEN, openr, 
or LBRET) is issued, register 13 must contain the 
address of the save area associated with the task. 
The fact that the save areas are unique for each task 
makes the module reentrant (that is, capable of be- 
ing used concurrently by several tasks). 

If the operand is omitted, the module generated is 
not reenterable and no save area is required. 

READ= (FORWARDIBACK) : This operand gen- 
erates a module that reads tape files forward or 
backward. If forward is specified, only code to read 
tape forward is generated. Any DTP used with the 
module must not specify BACK in the READ parame- 
ter statement. 

If the parameter is BACK, code to read tape both 
forward and backward is generated, and any DTP 
used with the module may specify either porward 
or BACK as its READ parameter. read=back does 
not handle multi-volume files. 

This entry is not needed for work files. 

RECFORM= (FIXUNB|FIXBLK|VARUNB| 
VARBLKjSPNBLKISPNUNBI 
UNDEF}: 

This operand generates an input/output module 
that processes either EBCDIC or ASCII fixed-length, 
variable-length, or undefined records. 

If PIXUNB or PIXBLK is specified, a module is 
generated that allows processing of both fixed-length 
blocked and fixed-length unblocked records. Simi- 
larly, if VARUNB/SPNUNB or VARBLK/SPNBLK is 
specified, a module is generated that allows process- 
ing of both types of variable and spanned records. 
ASCII files are not permitted in spanned record for- 
mat. 

If UNDEP is specified, a module for processing 
undefined record types is generated. Any DTP used 
with the module must specify the same record for- 
mat type as the module. For example, if the module 
specifies RECP0RM=PIXUNB, either 
RECPORM=PIXUNB Or RECPORM=PIXBLK may be 
specified in the DTP. 

This operand is not needed for work files. 

If this operand is omitted, the module generated 
will allow processing of both fixed-length blocked 
and fixed-length unblocked records. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and the module to be defined as an entry 
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point in the assembly. If the operand is omitted, the 
assembler assumes that the module is being assem- 
bled with the DTF and the problem program and no 
CATALR card is punched. 

TYPEFLE= (OUTPUT IINPUTIWORK) : This 
operand generates a module that processes either 
GET/PUT macros or read/write, note/pointx and 
CHECK macros for work files (EBCDIC only). If the 
parameter of the operand specifies work, code to 
process work files is generated. Otherwise, a module 
to handle both input and output files is assumed. 
Only DTPS for work files may be used with work file 
modules. Only dtps for input or output files may be 
used with an input/output mouuic. 

Note: INPUT and OUTPUT have the same table fonnat and 
logic modules. 

WORKA=YES: This operand is to be included if 
records are to be processed in work areas instead of 
I/O areas for the get/put macros. This operand 
must be included if spanned records are processed. 
The module also processes files that do not use a 
work area. This entry is not needed for work files. 

Standard MTMOD Names 

Each name begins with a 3-character prefix (UP) and 
continues with a 5 -character field containing the 
options permitted in module generation. In MTMOD 
there are two module classes: the module class for 
handhng GET/PUT functions and the module class 
for handling READ/WRITE, NOTE/POlNTx, and 
CHECK functions (work files). Modules handling 
fixed-length (P and x) and undefined (U and N) re- 
cords are mutually exclusive of each other and of all 
forms of the module that process variable-length 
records (V, R, and s). 

Nam.e list for GET/PUT type modules: 

MTMOD name = IJPabcde 

a = P RECPORM=PIXUNB (or PIXBLK) (EBCDIC 
mode) 
= X RECPORM=PIXUNB (or PIXBLK) (ASCII mode) 
= V RECPORM=VARUNB (or VARBLK) (EBCDIC 

mode) 
= R RECPORM=VARUNB (or VARBLK) (ASCII mode) 
= S RECPORM=SPNUNB (or SPNBLK) (spanned re- 
cords) 
= U RECPORM=UNDEP (EBCDIC mode) 
= N RECPORM=UNDEP (ASCII mode) 

b = B READ=BACK 

= Z READ=FORWARD, or if READ is not specified 



c = C CKPTREC=YES 

= Z CKPTREC= YES is not specified 

d = W WORKA=YES 

= Z WORKA=YES is not specified 

e = M ERREXT=YES and RDONLY=YES 

= N ERREXT=YES 

= Y RDONLY=YES 

= Z EP.REXT and RDONLY not specified 

Name list for work file type modules 

(TYPEPLE=WORK): 

MTMOD name = IJPabcde 
a = W 

b = E ERROPT=YES 

= Z ERROPT is not specified 

c = N NOTEPNT=YES 
= S NOTEPNT=POINTS 
= Z NOTEPNT is not specified 

d = Z always 

e = M ERREXT=YES and RDONLY=YES 

= N ERREXT=YES 

= Y RDONLY=YES 

= Z ERREXT and RDONLY not specified 

Subset/Superset MTMOD Names 

The charts in Figure 3-33 illustrate the subsetting 
and supersetting allowed for MTMOD names. Four 
of the GET/PUT parameters allow subsetting. For 
example, the module name UPPBCWZ is a superset of 
IJPPBZWZ specifying fixed-length records. 



For GET/PUT Type Modules: 
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+ Subsetting/supersetting permitted. 


* No subsetting/supersetting permitted. 



Figure 3-33. Subsetting and supersetting of MTMOD names. 
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DTFOR Macro 

DTFOR is used to define an input file to be processed on a 1287 optical reader or 1288 optical page reader. The 
macro is not used for the 3881 optical mark reader; for the 3881, use the dtfcd macro. 



Applies to 








1287T 


1287D 


1288 




X 


X 


X 


M 


COREXIT=xxxxxxxx 


Name of your correction routine 


X 


X 


X 


M 


DEVADDR=SYSnnn 


Symbolic unit assigned to the optical reader 


X 


X 


X 


M 


EOF ADDR = xxxxxxxx 


Name of your end-of-file routine 


X 


X 


X 


M 


I0AREA1 =xxxxxxxx 


Name of first input area 


X 









BLKFAC=nn 


If RECFORM = UNDEF in journal tape mode 


X 


X 


X 





BLKSlZE = nn 


Length of I/O area(s). If omitted, 38 is assumed. 


X 


X 


X 





CONTROL=YES 


If CNTRL macro is to be used for this file 


X 


X 


X 





DEVICE=xxxxx 


(1 287D or 1 287T). For 1 288, specify 1 287D. If omitted, 
1287D is assumed. 


X 


X 







HEADER = YES 


If a header record is to be read from the optical reader key- 
board by OPEN, OPENR 




X 


X 





HPRMTY=YES 


If hopper empty condition is to be returned. 


X 









I0AREA2 =xxxxxxxx 


If two input areas are used, name of second input area. 


X 









IOREG=(nn) 


Register number if 2 input areas or UNDEF records are to be 
used. If omitted, register 2 is assumed. General registers 
2-12, written in parentheses. 


X 


X 


X 





MODNAME=xxxxxxxx 


Name of DTF's logic module. If omitted, IOCS generates a 
standard name. 


X 


X 


X 





RECFORM = xxxxxx 


(FIXBLK. FIXUNB, or UNDEF). If omitted, FIXUNB is assumed. 


X 


X 


X 





RECSIZE=(nn) 


Register number containing record size, if RECFORM = UNDEF. 
If omitted, register 3 is assumed. 


X 


X 


X 





SEPASMB=YES 


If the DTFOR is to be assembled separately. 


X 









WORKA=YES 


If records are to be processed in a work area. Omit lOREG. 



M = Mandatory 
0=Optional 

Figure 3-34. DTFOR macro options. 

BLKFAC=n: Undefined journal tape records are 
processed with greater throughput speeds when this 
operand is included. This is accomplished by read- 
ing groups of lines as blocked records. When unde- 
fined records are processed, blkfac specifies the 
blocking factor (n) that determines the number of 
lines read (through ccw chaining) as a block of data 
by one physical read. Deblocking is accomplished 
automatically by IOCS when the GET macro is used. 
The BLKFAC parameter is not used with 
RECFORM=FlXBLK, because the blocking factor is 
determined from the blksize and RECSIZE parame- 
ters. If the operand is included for FIXBLK, FixUNB, 
or document processing, the operand is noted (in an 
MNOTE) and ignored. 

BLKSIZE= {38|n} : This operand indicates the 
size of the input area specified by lOAREAi. For 
journal tape processing, BLKSIZE specifies the maxi- 
mum number of characters that can be transferred 
to the area at any one time. 



When undefined journal tape records are read, 
the area must be large enough to accommodate the 
longest record to be read if the blkfac parameter is 
not specified. If the blkfac parameter is specified, 
the BLKSIZE value must be determined by multiply- 
ing the maximum length that must be accommodat- 
ed for an undefined record by the blocking factor 
desired. A BLKSIZE value smaller than this results in 
truncated data. 

If two input areas are used for journal tape proc- 
essing (lOAREAl and IOAREA2), the size specified in 
this entry is the size of each I/O area. 

CONTROL= YES: This entry must be included if 
a CNTRL macro is issued for a file. A cntrl macro 
issues orders to the optical reader to perform nonda- 
ta operations such as line marking, stacker selecting, 
document incrementing, etc. 
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COREXIT=name: COREXIT provides an exit to 
your error correction routine for the 1287 or 1288. 
After a GET, WAITF, or CNTRL macro is executed (to 
increment or eject and/or stacker select a docu- 
ment), an error condition causes an error correction 
routine to be entered with an error indication pro- 
vided in filename-l-80. The byte at filename-f-80 
contains the following codes indicating the condi- 
tions that occurred during the last line or field read. 
The byte should also be tested after issuing the opti- 
cal reader macros DSPLY, RESCN, rdlne, cntrl 
READKB, and CNTRL MARK. More than one error 
condition may be present. 



Code Meaning 



Dec 

1 



Hex 

X'or 



A data check has occurred. Five read 
attempts for journal tape processing or 
three read attempts for document proc- 
essing were made. 

X'02' The operator corrected one or more char- 
acters from the keyboard (1 287T) or a 
hopper empty condition (see 
HPRMTY=YES operand) has occurred 
(1287D). 

X'04' A wrong-length record condition has 

occurred (for journal tapes, five read at- 
tempts were made; for documents, three 
read attempts were made). Not applicable 
for undefined records. 

X'08' An equipment check resulted in an incom- 
plete read (ten read attempts were made 
for journal tapes or three for documents). 

If an equipment check occurs on the first 
character in the record, when processing 
undefined journal tape records, the 
RECSIZE register contains zero, and the 
lOREG (if used) points to the rightmost 
position of the record in the I/O area. 
You should test the RECSIZE register be- 
fore moving records from the work area 
or the I/O area. 

A nonrecoverable error occurred. 

For the 1 288, reading in unformatted 
mode, the end-of-page (EOF) condition 
has been detected. Normally, on an EOF 
indication, the problem program ejects 
and stacker selects the document. 

After issuing one of the macros CNTRL 
ESD, CNTRL SSD, CNTRL EJD in your 
COREXIT routine, a late stacker selection 
condition occurred. 

For the 1 287, a stacker select was given 
after the allotted elapsed time and the 
document was put in the reject pocket. 

64 X'40' The 1287D scanner was unable to locate 

the reference mark (for journal tapes, ten 
read attempts were made; for documents, 
three read attempts were made). 

The byte filename+80 can be interrogated to 
determine the reason for entering the error correc- 
tion routine. Choice of action in your error correc- 
tion routine is determined by the particular applica- 
tion. 



16 



X'10' 
X'20' 



If you issue I/O macros to any device other than 
the 1287 and/or 1288 in the COREXIT routine, you 
must save registers 0, 1, 14, and 15 upon entering the 
routine, and restore these registers before exiting. 
Furthermore, if I/O macros (other than the GET, 
WAITF, and/or read, which cannot be used in 
COREXIT) are issued to the 1287 and/or 1288 in this 
routine, you must also save and later restore regis- 
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COREXIT should be to the address specified in regis- 
ter 14. This provides a return to the point from 
which the branch to COREXIT occurred. If the com- 
mand chain bit is on in the READ ccw for which the 
error occurred, IOCS completes the chain upon re- 
turn from the COREXIT routine. 

Note: Do not issue a GET, READ, OPEN, or WAITF macro to 
the 1287 or 1288 in the error correction routine. Do not process 
records in the error correction routine. The record that caused the 
exit to the error routine is available for processing upon return to 
the mainline program. Any processing included in the error 
routine would be duplicated after return to the mainline program. 

When processing journal tapes, a nonrecovery 
error (torn tape, tape jam, etc.) normally requires 
that the tape be completely reprocessed. In this case, 
your routine must not branch to the address in regis- 
ter 14 from the COREXIT routine or a program loop 
will occur. Following an unrecoverable error: 

• the optical reader file must be closed. 

• the condition causing the nonrecovery must be 
cleared. 

• the file must be reopened before processing can 
continue. 

If a nonrecoverable error occurs while processing 
documents (indicating that a jam occurred during a 
document incrementation operation, or a scanner 
control failure has occurred, or an end-of-page con- 
dition, etc.), the document should be removed either 
m.anually or by nonprocess mnout. In such cases, 
your program should branch to read the next docu- 
ment. 

If the 1287 or 1288 scanner is unable to locate the 
document reference mark, the document cannot be 
processed. In this case, the document must be eject- 
ed and stacker selected before attempting to read the 
following document or a program loop will result. 

Whenever a nonrecoverable error occurs, your 
COREXIT routine must not branch to the address in 
register 14 to return to IOCS. Instead, the routine 
should ignore any output resulting from the docu- 
ment. 

Eight binary error counters are used to accumu- 
late totals of certain 1287 and 1288 error conditions. 
Each of these counters occupies four bytes, starting 
at filename-l-48. Filename is the name specified in 
the DTF header entrv'. The error counters are: 
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Counter and 

Address Contents 

1 filename + 48 Equipment check (see Note, below). 

2 filename + 52 Equipment check uncorrectable after 

ten read attempts for journal tapes or 
three read attempts for documents 
(see Note, below). 

3 filename+56 Wrong-length records (not applicable 

for undefined records). 

4 filename+60 Wrong-length records uncorrectable 

after five read attempts for journal 
tapes or three read attempts for docu- 
ments (not applicable for undefined 
records). 

5 filename + 64 Keyboard corrections (journal tape 

only). 

6 filename + 68 Journal tape lines (including retried 

lines) or document fields (including re- 
tried fields) in which data checks are 
present. 

7 filename + 72 Lines marked (journal tape only). 

8 filename+76 Count of total lines read from journal 

tape or the number of CCW chains ex- 
ecuting during document processing. 

Note: Counters 1 and 2 apply to equipment checks that result 
from incomplete reads or from the inability of the 1287 or 1288 
scanner to locate a reference mark (when processing documents 
only). 

All the previous counters contain binary zeros at 
the start of each job step. You may list the contents 
of these counters for analysis at end of file, or at end 
of job, or you may ignore the counters. The binary 
contents of the counters should be converted to a 
printable format. 

DEVADDR=SYSnnn: This operand specifies the 
logical unit (SYSnnn) to be associated with the file. 
The logical unit represents an actual I/O device ad- 
dress used in the ASSGN job control statement to 
assign the actual I/O device address to this file. 

DEVICE= (1287D I1287T1: This operand speci- 
fies the I/O device associated with this file. 1287D 
specifies a 1287 or 1288 document file. 1287T speci- 
fies a 1287 journal tape file. 

From this specification, IOCS sets up the device- 
dependent routines for this file. For document proc- 
essing you must code the ccws. 

If this operand is omitted, 1287D is assumed. 

EOFADDR=name: This operand specifies the 
name of your end-of-file routine, iocs automatical- 
ly branches to this routine on an end-of-file condi- 
tion. 

When reading data from documents, you can 
recognize an end-of-file condition by pressing the 
end-of-file key on the console when the hopper is 
empty. When processing journal tapes on a 1287, 



you can detect an end-of-file by pressing the end-of- 
file key after the end of the tape is sensed. 

When IOCS detects an end-of-file condition, it 
branches to your routine specified by eofaddr. 
You must determine whether the current roll is the 
last roll to be processed when handling journal 
tapes. Regardless of the situation, the tape file must 
be closed for each roll within your EOF routine. If 
the current roll is not the last, OPEN (or openr) must 
be issued. The open (or openr) macro allows head- 
er (identifying) information to be entered at the 
reader keyboard and read by the processor when 
using logical IOCS. 

The same procedure can be used for 1287 proc- 
essing of multiple journal tape rolls, as well as the 
method described under "open (or OPENR) Macro" 
in the section "Imperative Macros". 

HEADER=YES: This operand cannot be used for 
1288 files. This operand is required if the operator is 
to key in header (identifying) information from the 
1287 keyboard. The open (or OPENR) routine reads 
the header information only when this entry is pre- 
sent. If the entry is not included, OPEN (or OPENR) 
assumes no header information is to be read. The 
header record size can be as large as the blksize 
entry and is read into the high-order positions of 

lOAREAl. 

HPRMTY=YES: This operand is included if you 
want to be informed of the hopper empty condition. 
This condition occurs when a read is issued and no 
document is present, and is recognized at wait? 
time. When a hopper empty condition is detected, 
your COREXIT routine is entered with X'02' stored in 
filename-t-80. 

This operand should be used when processing 
documents in the time-dependent mode of opera- 
tion, which allows complete overlapping of process- 
ing with reading. See the appropriate IBM 1287 de- 
vice manuals for processing details. With this me- 
thod of processing, specifying hprmty=yes allows 
you to check for a hopper empty condition in your 
COREXIT routine. You can then select into the prop- 
er hopper the previously ejected document before 
return from COREXIT (via register 14). 

IOAREAl=name: This operand is included to 
specify the name of the input area used by the file. 
When opening a file and before each journal tape 
input operation to this area, the designated area is 
set to binary zeros and the input routines then trans- 
fer records to this area. For document processing, 
the area is cleared only when the file is opened. 
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IOAREA2=name: A second input area can be al- 
lotted only for a journal tape file. This permits an 
overlap of data transfer and processing operations. 
The specified second I/O area is set to binary zeros 
before each input operation to this area occurs. 

IOREG= {(2^)|(r)} : This operand specifies a 
general-purpose register (any one of 2 to 12) that the 
input routines use to indicate the beginning of re- 
cords for a journal tape file. The same register may 
be specified in the lOREG operand for two or more 
files in the same program, if desired. In this case, 
your program may need to store the address sup- 
plied by IOCS for each record. Whenever this entry 
is included for a file, the DTFOR entry WORKA must 
be omitted, and the GET macro must not specify a 
work area. 

A read by an optical reader is accomplished by a 
backward scan. This places the rightmost character 
in the record in the rightmost position in the I/O area 
and subsequent characters in sequence from right to 
left. The register defined by lOREG indicates the 
leftmost position of the record. 

MODNAME=name: This operand may be used to 
specify the name of the logic module used with the 
DTP table to process the file. If the logic module 
(ORMOD) is assembled with the program, the 
MODNAME parameter in this DTP must specify the 
same name as the ORMOD macro. 

If this entry is omitted, standard names are gener- 
ated for calling the logic module. If two different 
DTP macros call for different functions that can be 
handled by a single module, only one standard- 
named module is called. 

RECFORM= {FIXUNB|FIXBLK|UNDEF} : 
This operand specifies the type of records in an opti- 
cal reader file. One of the following mav be speci- 
fied: 

PIXUNB For fixed-length unblocked records. 

PIXBLK Por fixed-blocked records in journal tape mode. 

UNDEP Por undefined records. 

RECSIZE= n| {(3)|(r)) : For fixed-length un- 



blocked records, this operand should be omitted and 
no register is assumed. 

For fixed-length blocked records (journal tape 
mode), this operand must be included to specify the 
number, n, of characters in an individual record. 
The input routines use this number to deblock re- 
cords, and to check the length of input records. If 
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emitted, an MNOTE is nagged in the 
macro assembly and fixed-length unblocked records 
are assumed. 

For undefined journal tape records, this entry 
specifies the number (r) of the general-purpose reg- 
ister in which IOCS provides the length of each input 
record. For undefined document records, RECSIZE 
contains only the length of the last field of a docu- 
ment read by the ccw chain that you supply. Any 
one of registers 2 through 12 may be specified, but if 
the operand is omitted, register 3 is assumed. 

Note: When processing undefined records in document mode, 
you gain complete usage of the register normally used in the 
RECSIZE operand. You can do this by ensuring that the 
suppress-length-indication (SLI) flag is always on when process- 
ing undefined records. 



SEPASMB=YES: Include this operand only if the 
DTPOR will be assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and the filename to be defined as 
an ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the DTP is being 
assembled with the problem program and no 
CATALR card is punched. 

WORKA=YES: Input records (journal tape only) 
can be processed in work areas instead of in the in- 
put areas. If this is planned, the operand 
WORKA=YES must be specified, and you must set up 
the work area in storage. The symbolic name of the 
work area, or a general-purpose register containing 
the address of the work area, must be specified in 
each GET macro. When GET is issued, IOCS left- 
justifies the record in the specified work area. 
Whenever this operand is included for a file, the 
DTPOR lOREG Operand must be omitted. 
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ORMOD Macro 

Listed here are the operands you can specify for 
ORMOD. The first card contains ORMOD in the oper- 
ation field and may contain a module name in the 
name field. 

Note: ORMOD is not used for the 3881 Optical Mark Reader. 
The 3881 uses CDMOD. 

BLKFAC=YES: Include this operand if 
RECFORM=UNDEF and groups of undefined journal 
tape records are to be processed as blocks of data. 
(See the DTFOR BLKFAC=n operand.) The DTFOR 
used with this module must also include 

RECFORM=UNDEF and BLKFAC=n. 

CONTROL=YES: Include this operand if CNTRL 
macros are to be used with the associated DTFs. The 
module also processes files that do not use the 
CNTRL macro. 

DEVICE= {1287DI 1287T} : This operand must be 
included to specify the I/O device associated with 
this file. 1287D specifies a 1287 or 1288 document 
file. 1287T specifies a 1287 journal tape file. 

IOAREA2=YES: Include this operand (journal 
tape only) if a second I/O area is used. The DTFOR 
used with this module must also include the 
IOAREA2 parameter. 

RECFORM= (FIXUNB |FIXBLK|UNDEF1 : 
This operand generates a module that processes the 
specified record format. Any DTF used with the 
module must have the same operand. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and the module name to be defined as an 
ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the ORMOD 
macro is being assembled with the DTF and the 
problem program and no CATALR card is punched. 



WORKA=YES: Include this operand (journal tape 
only) if records are to be processed in work areas 
instead of in I/O areas. Any dtf used with the mo- 
dule must have the same operand. 

Standard ORMOD Names 

Each name begins with a 3-character prefix (IJM) 
followed by a 5-character field corresponding to the 
options permitted in the generation of the module. 

ORMOD name = IJMabcde 

a = F RECFORM=FIXUNB 

= X RECFORM=FIXBLK 

= U RECFORM=UNDEF 

= D RECFORM=UNDEF and BLKFAC=YES 

b = C CONTROL=YES 

= Z CONTROL^ YES is not specified 

c = I I0AREA2=YES 

= W WORKA=YES 

= B both are specified 

= Z neither is specified 

d = T device is in tape mode 
= D device is in document mode 

e = Z always 

Subset/Superset ORMOD Names 

Figure 3-35 shows the subsetting and supersetting 
allowed for ORMOD names. One of the parameters 
allows subsetting. For example, the module 
IJMFCITZ is a superset of the module umfzitz. 



* + * * 

J M D C B D Z 

F Z I T 
U W 
X Z 



+ Subsetting/supersetting permitted. 
* No subsetting/supersetting permitted. 



Figure 3-35. Subsetting and supersetting of ORMOD names. 
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DTFPH Macro 

When physical IOCS macros (EXCP, WAIT, etc.) are used in a program, DASD, diskette, or tape files with 
standard labels need to be defined by the DTFPH macro (dtfxx macro for a file handled by physical IOCS). 
DTFPH must also be used for a checkpoint file on a disk. 



M 


TYPEFLE=xxxxxx 


(INPUT or OUTPUT). Specifies type of file. 





ASCII = YES 


ASCII file processing is required. 





CiSiZE = n 


For Fixed Block Architecture DASD, Control Interval size. 





CCWADDR = xxxxxxxx 


If CCB is generated by DTFPH is to be used. 


o 


DEVICE=xxxx 


(TAPE, FBA, 231 1 , 2314, 3330, 3340, 3350. 3540). If omitted, TAPE is assumed. 


o 


DEVADDR=SYSxxx 


Symbolic unit required only when not provided on an EXTENT statement. 





HDRINFO=YES 


Print header label information. 


o 


LABADDR=xxxxxxxx 


Routine to check or build user standard labels. 





MOUNTED=xxxxxx 


(ALL or SINGLE). Required for DASD files only; for diskette files, specify SINGLE. 





XTNTXIT=xxxxxxxx 


If EXTENT statements are to be processed. DASD only. 



M= Mandatory 
0= Optional 

Figure 3-36. DTFPH macro. 

Figure 3-37 shows which of the DTFPH entries can or 
must be coded to define a checkpoint file on disk. 



Operand 


Optional 


Required 


CCWADDR = name 


X 




CISIZE = n 


X 




DEVADDR = SYSnnn 


X 




DEVICE=2311, 2314, 3330, 
3340, 3350, 3540, FBA 




X 


LABADDR = name 


X 




MOUNTED=SINGLE 




X 


TYPEFLE=OUTPUT 




X 



Figure 3-37. Operands to define a checkpoint file on disk. 

ASCII=YES: This operand is required to process 
ASCII tape files. If this operand is omitted, EBCDIC 
processing is assumed. 

CCWADDR=name: This operand allows you to 
use the CCB generated within the first 16 bytes of the 
DTFPH table. CCWADDR Specifies the symbolic name 
of the first ccw used with the CCB generated within 
the DTFPH macro. This name must be the same as 
the name specified in the assembler CCW statement 
that constructs the CCW. 

If this operand is omitted, the location counter 
value of the CCB-Ccw table address constant is sub- 
stituted for the CCW address. 

CISIZE=n: This operand specifies the FBA Control 
Interval size. The value n must be an integral multi- 
ple of the FBA logical block size and, if greater than 
8K, must be a multiple of 2K. The maximum value is 



32768 (32K) except when assigned to SYSLST or 
SYSPCH, when the maximum is 30720 (30K). 

If DEVICE=FBA is Specified, and CISIZE is omitted, 
CISIZE=0 is assumed. Control Interval size may be 
overridden for an output file at execution time by 
specifying the ciSiZE parameter of the DLBL job 
control statement. For an input file, the cisiZE value 
in the format- 1 label is used. 

DEVICE=(TAPE|FBA|2311|2314|3330|3340| 

335013540} : 
If the file is contained on DASD or diskette, enter the 
proper identification. 

TAPE applies to 8809 and any 2400/3400-series 
tape unit, and is the only valid entry in this operand 
for ASCII files. 

FBA applies to 33 10 and 3370. 

For devices supported by DOS/VSE and not in- 
cluded in the above operand specification, specify 
device codes as listed in Figure 3-38. 



DEVADDR=SYSxxx: This operand must specify 
the symbolic unit (SYSxxx) associated with the file if 
a symbolic unit is not provided via an EXTENT job 
control statement. If a symbolic unit is provided, its 
specification overrides a DEVADDR specification. 
This specification, or symbolic unit, represents an 
actual I/O address, and is used in the ASSGN job 
control statement to assign the actual I/O device 
address to this file. 

If SYSLST or SYSPCH are used as output tape units 
and alternate tape switching is desired upon detect- 
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DEVICE = 
specification 


Device in use 


2311 


2314 


2319 


3330-1,2* 


3330-11** 


3340, 35MB 


3340, 70MB 


3350 


TAPE 


3310, 3370 


TAPE 


















X 




2311 


X 








X 






X 




X 


2314 




X 


X 




X 






X 




X 


3330 








X 


X 






X 




X 


3340 










X 


X 


X 


X 




X 


3350 










X 






X 




X 


FBA 




















X 



* Also 3350 in 3330-1 compatibility mode. 

* * Also 3350 in 3330-1 1 compatibility mode. 

Figure 3-38. DEVICE= specifications for DTFPH. 

ing a reflective spot, the SEOV macro must be used 
(see "SEOV Macro"). When processing ASCII tape 
files, the only valid specification is a programmer 
logical unit (that is, SYSnnn). 

HDRINFO=YES: This operand causes IOCS to 
print standard header label information (fields 3-10) 
on SYSLOG each time a file with standard labels is 
opened. Likewise, the filename, symbolic unit, and 
device address are printed each time an end-of- 
volume condition is detected. If HDRlNFO=YES is 
omitted, no header or end-of- volume information is 
printed. 

LABADDR=name: This operand does not apply to 
diskette input/output units. 

You may require one or more dasd or tape labels 
in addition to the standard file labels. If so, you 
must include your own routine to check (on input) 
or build (on output) your label(s). Specify the sym- 
bolic name of your routine in this operand. IOCS 
branches to this routine after the standard label is 
processed. 

LABADDR may be included to specify a routine 
for your header or trailer labels as follows: 

• DASD input or output: header labels only. 

• Tape input or output: header and trailer labels. 

Thus, if LABADDR is specified, your header labels 
can be processed for an input/output dasd or tape 
file, and your trailer labels can be built for a tape 
output file. Physical IOCS reads input labels and 
makes them available to you for checking, and 
writes output labels after they are built. This is simi- 
lar to the functions performed by logical IOCS. 

If physical IOCS macros are used for a tape file, an 
OPEN must be issued for the new volume. This caus- 



es IOCS to check the hdri label and provides for 
your checking of user standard labels, if any. 

When physical IOCS macros are used and dtfph 
is specified for standard tape label processing, FEOV 
must not be issued for an input file. 

MOUNTED= {ALL|SINGLE} This operand does 
not apply to diskette input/output units. 

This operand must be included to specify how 
many extents (areas) of the file are available for 
processing when the file is initially opened. This 
operand must not be specified for tape. 

ALL is specified if all extents are available for 
processing. When a file is opened, IOCS checks all 
labels on each disk pack and makes available all 
extents specified by your control statements. Only 
one OPEN or openr is required for the file. ALL 
should be specified whenever you plan to process 
records in a manner similar to the direct access me- 
thod. In any case, you must supply an lbltyp state- 
ment. 

JS[«<«; 0BtS5^«ias witfe VSE/Advaa«ed Foactions installed^ tib^e 
LBITYP s|».|:«ia6!aiit i& net Jfe^SiaiJe^* 

After an OPEN or OPENR is performed, you must 
be aware that the symbolic unit address of the first 
volume containing the file is in bytes 30 and 3 1 of 
the DTFPH table rather than in the CCB. Therefore, 
place this symbolic address into bytes 6 and 7 of the 
associated CCB before you issue an EXCP against this 
CCB in your program. 

SINGLE is specified if only the first extent on the 
first volume is available for processing, single 
should be specified when you plan to process re- 
cords in sequential order. IOCS checks the labels on 
the first pack and makes the first extent specified by 
your control cards available for processing. You 
must keep track of the extents and issue a subse- 
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quent open or openr whenever another extent is 
required for processing. You will find the informa- 
tion in the DTFPH table helpful in keeping track of 
the extents. The dtfph table contains: 



Bytes 


Contents 


0-15 


CCB (symbolic unit has been initialized in 
CCB). 


the 


54-57 


ExiSmi upper lirpiits ^ccmi/. 




58-59 


Seek address. For a disk it must be zero. 




60-63 


Extent lower limit (cctih). 





On each open or OPENR after the first, iocs 
makes available the next extent specified by the 
control cards. When you issue a close or CLOSER 
for an output file, the volume on which you are cur- 
rently writing records is indicated, in the file label, 
as the last volume for the file. 

TYPEFLE= {INPUT! OUTPUT}: This operand 
must be included to specify the type of file: input or 
output. 

XTNTXIT=name: This operand does not apply to 
diskette input/output units. 

This entry is included if you want to process label 
extent information. It specifies the symbolic name 
of your extent routine. The dtfph operand 
MOUNTED=all must also be specified for the file. 

Whenever XTNTXIT is included, IOCS branches to 
your routine during the initial OPEN for the file. It 



branches after each specified extent is completely 
checked and after conflicts, if any, have been re- 
solved. 

When your routine receives control, register 1 
contains the address of a 14-byte area from which 
you can retrieve label extent information (in binary 
form). The layout of this area is shown in Figure 

■3 on 

Return to IOCS by using the LBRET macro. 



Bytes 


Contents 





Extent type code: 




00 Next three fields do not indicate any 




extent. 




01 The extent containing your data record. 




02 Overflow area of an indexed sequential 




file. 




04 Cylinder index or master index of an 




indexed sequential file. 




40 User label track area 




80 Shared cylinder indicator 


1 


Extent sequence number. 


2-5 


Lower limit of the extent (cchh). 


6-9 


Upper limit of the extent (cchh). 


10-11 


Symbolic unit (see Figure 2-1 ). 


12 


Contains zero. 


13 


Not used. 



Figure 3-39. Layout of XTNTXIT information area. 
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DTFPR Macro 

DTFPR is used to define an output file for a printer. 



M 


DEVADDR = SYSxxx 


Symbolic unit for the printer used for this file. 


M 


I0AREA1 =xxxxxxxx 


Name for the first output area. 





ASOCFLE = xxxxxxxx 


Name of the associated file for FUNC = RW, RPW, PW. 





BLKSIZE=nnn 


Length of one output area, in bytes. If omitted, 121 is assumed for 1403, 1443, 3203 or 
321 1 ; 1 36 is assumed for 3800 without TRC (or 1 37 with TRC): 64 is assumed for 2560 
or 3525; 96 is assumed for 5203 or 5424/5425.' 





CONTROL=YES 


CNTRL macro used for this file. Omit CTLCHR for this file. Not allowed for 2560 or 
5424/5425. 





CTLCHR = xxx 


(YES or ASA). Data records have control character. YES for S/370 character set; ASA 
for American National Standards Institute character set. Omit CONTROL for this file. Not 
allowed for 2560 or 5424/5425. 





DEVICE=nnn 


(1403, 1443, 2560P, 2560S, 3203, 321 1 , 3525, 3800, 5203. Specify 5425P or 5425S 
for 5424/5425 (P or S). Specify PRT1 for 3203-4, 3203-5, 321 1 , or 3289-4. If omitted, 
1403 is assumed.' 





ERROPT=xxxxxxxx 


RETRY or the name of your error routine for 321 1 . IGNORE for 3525. Not allowed for 
other devices.' 





FUNC=xxxx 


(W, RW, RPW, PW) for 2560 or 5424/5425. (W[T]. RW[T]. RPW[T], PW[T] for 3525. 





10 AREA2 = xxxxxxxx 


If two output areas are used, name of second area. 





IOREG=(nn) 


Register number, if two output areas used and PUT does not specify a work area. Omit 
WORKA. 





MODNAME=xxxxxxxx 


Name of PRMOD logic module for this DTF. If omitted, IOCS generates standard name. 
Not needed with 3800 advanced printer buffering. 





PRINTOV=YES 


PRTOV macro used for this file. Not allowed for 2560 or 5424/5425. 





RDONLY=YES 


Generate a read-only module. Requires a module save area for each task using the 
module. 


O 


RECFORM=xxxxxx 


(FIXUNB, VARUNB, or UNDEF). If omitted, FIXUNB is assumed. 





RECSIZE=(nn) 


Register number if RECFORM = UNDEF. 





SEPASMB=YES 


DTFPR is to be assembled separately. 





STL1ST=YES 


1 403 selective tape listing feature is to be used. 





TRC=YES 


For 3800, output data lines include table reference character. 





UCS=xxx 


(ON) process data checks. (OFF) ignores data checks. Only for printers with the UCS 
feature, 321 1 , or 3800. If omitted, OFF is assumed.' 





WORKA=YES 


PUT specifies work area. Omit lOREG. 



M = Mandatory 
0=Optional 

' 321 1 remarks apply also to 321 1 -compatible printers (that is, with a device type code of PRTl). 
Figure 3-40. DTFPR macro operands. 



ASOCFLE=filename; This operand is used to- 
gether with the FUNC operand to define associated 
files for the 2560, 3525, or 5424/5425. (For a de- 
scription of associated files see DOS/ VSE Data 
Management Concepts, as listed in the Preface.) 
ASOCFLE specifies the filename of an associated read 
and/or punch file, and enables macro sequence 



checking by the logic module of each associated file. 
One filename is required per DTF for associated 
files. 

Figure 3-41 defines the filename specified by the 
ASOCFLE operand for each of the associated DTFs. 
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Code in FUNC= operand 


1 
filename specification in ASOCFLE = operand of | 


read DTFCD 


punch DTFCD 


print DTFPR 


FUNC=RPW 


filename of punch DTFCD 


filename of print DTFPR 


filename of read DTFCD 


FUNC=PW 




filename of print DTFPR 


filename of punch DTFCD 


FUNC=RW 


filename of print DTFPR 




filename of read DTFCD 


Exampies: 

1. If FUNC = PW is specified, 

a. specify the filename of the print DTFPR in the ASOCFLE operand of the punch DTFCD and 

b. Specify the filename of the punch DTFCD in the ASOCFLE operand of the print DTFPR. 

2. If FUNC = RPW is specified, 

a. specify the filename of the punch DTFCD in the ASOCFLE operand of the road DTFCD, and 

b. specify the filename of the print DTFPR in the ASOCFLE operand of the punch DTFCD, and 

c. specify the filename of the read DTFCD in the ASOCFLE operand of the print DTFPR. 



Figure 3-4 L ASOCFLE operand usage with print associated files. 

BLKSIZE=nnn: This operand specifies the length 
of lOAREAi. The maximum values which may be 
specified in this operand and the lengths assumed 
when it is omitted are given for the different devices 
in Figure 3-42. 



CONTROL=YES: This operand is specified if the 
CNTRL macro will be issued for the file. If this ope- 
rand is specified, omit CTLCHR. This operand is not 
allowed for the 2560 or 5424/5425. 

CTLCHR= (YESIASA): This operand is specified 
if first-character control is used. The parameter ASA 
specifies the American National Standards Institute, 
Inc. character set. The entry CTLCHR=YES specifies 
the s/370 character set. If this parameter is specified, 
omit CONTROL. This operand must not be specified 
for the 2560 or 5424/5425. 

If CTLCHR=ASA is Specified for the 3525, the 4- 
character is not allowed. To print on the first line of 
a card, you must issue either a space 1 command or 
a skip to channel 1 command. For 3525 print associ- 
ated files, you must issue a space 1 command to 
print on the first line of a card. 

DEVADDR={SYSLOG|SYSLST|SYSnnn}: 

This operand specifies the symbolic unit to be asso- 
ciated with the printer. SYSLOG and SYSLST must 
not be specified for the 2245, 2560, 3525, or 
5424/5425. 



Devices 


Maximum length (in 
bytes) which can be 
specified ' 


Length assumed (in 
bytes) 2 


1403-1,-4 


100 


121 


1403-6,-7 


120 


121 


1403-2,-3,- 
5, -8, -9 


132 


121 


1443 


144 


121 


2560 


384 


64 


3203 


132 


121 


3203-4, -5 


132 


121 


3211 


150 


121 


3289-4 


132 


121 


3525 


64 


64 


3800 


204 (without TRC)^ 


1 36 (without TRC)^ 


5203 


132 


96 


5424/5425 


128 


96 



RECFORM is FIXUNB or UNDEF and operand 
CTLCHR is not specified. 

The parameter BLKSIZE = n is omitted. 

For a 3800, the maximum length is 205 if TRC = YES 
is used, and the assumed length is 137. 



Notes: 

• If CTRCHR=YES/ASA is specified, add 1 byte to the 
maximum length which can be specified 

• If RECFORM=VARUNB is specified add 4 bytes to the 
maximum value which can be specified. 

• For the 2245, if RECFORM=VARUNB and 
CTLCHR=YES/ASA are specified, the maximum block- 
size is 805 bytes. 

Figure 3-42. Maximum and assumed lengths for the lOAREAl. 
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DEVICE= (1 4Q3 11443|2560P|2560S|32031 
|3211|3525|3800|5203|5425P| 
5425S|PRT1}: 
This operand specifies which device is used for the 
file. The "P" and "S" included with the "2560" and 
"5425" parameters specify primary or secondary 
input hoppers. Specify 5425P/S for 5424(P/S). 
"PRTl" refers to a 321 1 or 321 1 -compatible printer. 
If this operand is omitted, 1403 is assumed. 

ERROPT= {RETRYlIGNORE|name}: This ope- 
rand specifies the action to be taken in the case of an 
equipment check error. The functions of the param- 
eters are described below. 

RETRY can be specified only for a PRTl printer. 
RETRY indicates that if an equipment check with 
command retry is encountered, the command is 
retried once. If the retry is unsuccessful a message is 
issued and the job canceled. 

IGNORE can be specified only for the 3525. 
IGNORE indicates that the error is to be ignored. The 
address of the record in error is put in register 1 and 
made available for processing. Byte 3, bit 3 of the 
CCB is also set on (see Figure 4-2); you can check 
this bit and take the appropriate action to recover 
from the error, ignore must not be specified for 
files with two I/O areas or a work area. 

ERROPT=name can be specified only for a 321 1- 
compatible printer. It indicates that if an equipment 
check with command retry is encountered, the com- 
mand is retried once. If the retry is unsuccessful a 
message is issued and the job canceled. With other 
types of errors (for these see the CCB, Figure 4-2) an 
error message is issued, error information is placed 
in the CCB, and control is given to your error rou- 
tine, where you may perform whatever actions are 
desired. If any IOCS macros are issued in the rou- 
tine, register 14 must be saved; if the operand 
RDONLY=YES is Specified, register 13 must also be 
saved. To continue processing at the end of the rou- 
tine, return to IOCS by branching to the address in 
register 14. 

FUNC={WlTl|RWlT||RPWlT]|PWIT]}:This 

operand specifies the type of file to be processed by 
the 2560, 3525, or 5424/5425. w indicates print, R 
indicates read, P indicates punch, and T (for the 3525 
only) indicates an optional 2-line printer. 

RW[T], RPW[T], and pw[t] are used,together with 
the ASOCFLE operand, to specify associated files; 
when one of these parameters, other than T, is speci- 
fied for a printer file it must also be specified for the 
associated file(s). Note: Do not use T for associated 
files; it is vaUd only for printer files. 



If a 2-line printer is not specified for the 3525, 
multi-line print is assumed. T is ignored if CONTROL 
or CTLCHR is specified. 

IOAREAl=name: This operand specifies the name 
of the output area. 

IOAREA2=name: Jhis operand specifies the name 
of a second output area. 

IOREG=(r): If two output areas and no work areas 
are used, this operand specifies the register into 
which IOCS will place the address of the area where 
you can build a record. For (r) specify one of the 
registers 2 to 12. 

MODNAME=name: This operand may be used to 
specify the name of the logic module that is used 
with the DTP table to process the file. If the logic 
module is assembled with the program, modname 
must specify the same name as the PRMOD macro. If 
this operand is omitted, standard names are generat- 
ed for calling the logic module. If two DTP macros 
call for different functions that can be handled by a 
single module, only one module is called. 

PRINTOV=YES: This operand is specified if the 
PRTOV macro is included in your program. This 
operand is not allowed for the 2560 or 5424/5425. 

RDONLY=YES: This operand is specified if the 
DTP is used with a read-only module. Each time a 
read-only module is entered, register 13 must con- 
tain the address of a 72-byte doubleword-aUgned 
save area. Each task requires its own uniquely de- 
fined save area. Each time an imperative macro 
(except OPEN or OPENR) is issued, register 13 must 
contain the address of the save area associated with 
the task. The fact that the save areas are unique for 
each task makes the module reentrant (that is, capa- 
ble of being used concurrently by several tasks). 

If an ERROPT routine issues i/o macros which use 
the same read-only module that caused control to 
pass to either error routine, your program must pro- 
vide another save area. One save area is used for the 
normal I/O, and the second for I/O operations in the 
ERROPT routine. Before returning to the module 
that entered the erropt routine, register 13 must be 
set to the save area address originally specified for 
the task. 

If this operand is omitted, the module generated 
is not reenterable and no save area need be estab- 
lished. 
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RECFORM= (FIXUNB IUNDEFIVARUNB): 
The operand RECFORM=fixunb is specified when- 
ever the record format is fixed. When the record 
format is FIXUNB, this entry may be omitted. 

The entry RECFORM=UNDEF is specified when- 
ever the record format is undefined. If the output is 
variable and unblocked, enter varunb. 

RECSIZE=(r): This operand s'pecifies the general 
register (any one of 2 to 12) that will contain the 
length of an output record of undefined format. The 
length of each record must be loaded into the regis- 
ter before issuing the PUT macro 

SEPASMB=YES: Include this operand only if the 
DTFPR will be assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and the filename to be defined as 
an ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the DTF is being 
assembled with the problem program and no 
CATALR card is punched. 

STLIST=YES: Include this operand if the selec- 
tive tape listing feature (1403 only) is used. If this 
entry is specified, the CONTROL, CTLCHR, and 
PRINTOV entries are not valid and will be ignored if 
specified. If this operand is specified, recform 
must have the parameter FixuNB. 

TRC=YES: This operand applies to the 3800 Print- 
ing Subsystem; DEVICE=3800 should be specified. 



TRC=YES specifies that a table reference character is 
included as the first byte of each output data line 
(following the optional print control character). The 
printer uses the table reference character to select 
the character arrangement table corresponding to 
the order in which the table names have been speci- 
fied with the CHAR parameter on the setprt job 
control statement (or setprt macro instruction). 

If a printer other than a 3800 is specified on the 
DEVICE parameter, any table reference character 
sent to that printer is treated as data. 

UCS= (OFF ION) ; For a printer with the universal 
characier set feature, or for a 3800 Printing Subsys- 
tem, this operand determines whether data checks 
occurring in case of unprintable characters are indi- 
cated to the operator or printed as blanks. The entry 
is especially useful if you are using first-character 
forms control and have modules that cannot process 
the CNTRL macro. 

ON Data checks are processed with an operator 
indication. 

OFF Data checks are ignored and blanks are print- 
ed for the unprintable character. 

WORKA=YES: If output records are processed in 
work areas instead of in the I/O areas, specify this 
operand. You must set up the work area in storage. 
The address of the work area, or a general-purpose 
register which contains the address, must be speci- 
fied in each put macro. 
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PRMOD Macro: 

Listed here are the operands you can specify for 
PRMOD. The first card contains PRMOD in the opera- 
tion field and may contain a module name in the 
name field. 

If advanced printer buffering is used on your 
3800 Printer Subsystem, the PRMOD macro is not 
needed. 

CONTROL=YES: Include this operand if CNTRL 
macros are used with the associated DTFs. The mo- 
dule also processes files that do not use the cntrl 
macro. If CONTROL is specified, the ctlchr ope- 
rand must not be specified. 

The CONTROL operand is not allowed for the 
2560 or 5424/5425. 

CTLCHR= (YESjASA) : Include this operand if 
first-character carriage control is used. Any DTF 
used with the module must have the same operand. 
If CTLCHR is specified, CONTROL must not be speci- 
fied. 

CTLCHR must not be specified for the 2560 or 
5424/5425. 

If CTLCHR=ASA is Specified for the 3525, the + 
character is not allowed. For 3525 print (not associ- 
ated) files, you must issue either a space 1 command 
or skip to channel 1 command to print on the first 
line of a card. For 3525 print associated files, you 
must issue a space 1 command to print on the first 
line of a card. 

If CTLCHR=ASA and RDONLY=YES are specified 
in a multitasking environment where more than one 
DTFPR uses the same module, overprinting may oc- 
cur. 

DEVICE= (1403 |1443|2560P|2560S| 

3203|3211|3525|380015203i5425P| 
5425S|PRT1}: 

This operand specifies which device is used for the 
file. The "P" and "s" included with the "2560" and 
"5425" parameters specify primary or secondary 
input hoppers; regardless of which is specified, how- 
ever, the module generated will handle dtps speci- 
fying either hopper. Specify 5425P/S for 5424P/S. 

Any DTF to be used with this module must have 
the same operand (except as just noted concerning 
the "P" and "s" specification for the 2560 or 
5424/5425). 



specified in the DTFPR, or if erropt=retry (321 1) 
or ERROPT=iGNORE (3525) is specified, 
ERROPT=YES must be omitted. 

FUNC={WlTl|RWITl|RPWlTl|PWlTl}:This 

operand specifies the type of file to be processed by 
the 2560, 3525, or 5424/5425. Any DTF used with 
the module must include the same operand, w indi- 
cates print, R indicates read, P indicates punch, and 
T (for the 3525 only) indicates an optional 2-line 
printer. 

RW[T], RPW[T], and pw[t] are used to specify as- 
sociated files; when one of these parameters is speci- 
fied for a printer file it must also be specified for the 
associated file(s). 

If a 2-line printer is not specified for the 3525, 
multi-line print is assumed. T is ignored if CONTROL 
or CTLCHR is specified. 

IOAREA2=YES Include this operand if a second 
I/O area is used. Any DTF used with the module 
must also include the I0AREA2 operand. 

PRINTOV=YES Include this operand if PRTOV 
macros are used with the associated DTFs. The mo- 
dule also processes any files that do not use the 
PRTOV macro. 

This operand is not allowed for the 2560 or 
5424/5425. 

RDONLY=YES: This operand causes a read-only 
module to be generated. Whenever this operand is 
specified, any DTF used with the module must have 
the same operand. 

RECFORM= (FIXUNB |VARUNB|UNDEF1 : 
This operand causes a module to be generated that 
processes the specified record format: fixed-length, 
variable-length, or undefined. Any DTF used with 
the module must include the same operand. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and defines the module name as an ENTRY 
point in the assembly. If the operand is omitted, the 
assembler assumes that the module is being assem- 
bled with the DTF and the problem program and no 
CATALR card is punched. 



ERROPT=YES: This operand must be specified if 
ERROPT=name is specified in a DTFPR that is to be 
used with the module. (ERROPT=name is applicable 
to a 321 1 -compatible printer only.) If erropt is not 



STLIST=YES: Include this operand if the selec- 
tive tape listing feature (1403 only) is used. If this 
entry is specified, the CONTROL, CTLCHR, and 
PRINTOV entries are not valid, and are ignored if 
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supplied. If this operand is specified, RECFORM 
must specify FIXUNB. 

TRC= YES: Include this operand to specify wheth- 
er the module is to test the TRC bit in the dtfpr or 
iqnore that bit. If TRC=YES is specified, the generat- 
ed module can process output files with table refer- 
ence characters and those without. 

WORKA=YES: Include this operand if records are 
processed in work areas instead of in I/O areas. Any 
DTF used with the module must have the same ope- 
rand. 

Standard PRMOD Names 

Each name begins with a 3-character prefix (IJD) 
followed by a 5 -character field corresponding to the 
options permitted in the generation of the module. 

PRMOD name = IJDabcde 

a = F RECFORM=FIXUNB 
= V RECFORM=VARUNB 
= U RECFORM=UNDEF 



b = 



A CTLCHR=ASA 

Y CTLCHR=YES 
C CONTROL=YES 
S STLIST=YES 

Z none of these is specified 

T DEVICE=3525 with 2-line printer 

U DEVICE=2560 

V DEVICE=5425 



= I 



= F 



= C 



= T 



= E 



ERROPT=YES and PRINTOV=YES 

PRINTOV=YES, DEVICE is not 3525, and ERROPT 

is not specified 

PRINTOV=YES, DEVICE=3525, and FUNC=W[T] 

or omitted 

PRINTOV=YES, DEVICE=3525, and 

FUNC=RWm 

PRINTOV=YES, DEVICE=3525, and 

FUNC=PW[T] 

D PRINTOV=YES, DEVICE=3525, and 
FUNC=RPW[T] 

Z neither PRINTOV nor ERROPT is specified, and 
DEVICE is not a 3525 

O PRINTOV=YES not specified, DEVICE=3525, and 
FUNC=W[T] or omitted 

R PRINTOV=YES not specified, DEVICE=3525, and 
FUNC==RW[T] 

S PRINTOV=YES not specified, DEVICE=3525, and 

FUNC=PW[T] 

PRINTOV=YES not specified, DEVICE=3525, and 

FUNC=RPW[T] 

ERROPT=YES and PRINTOV=YES is not specified 
U FUNC=W or omitted and DEVICE=2560 or 5425 
V FUNC=RW and DEVICE=2560 or 5425 



= W FUNC=PW and DEVICE=2560 or 5425 
= X FUNC=RPW and DEVICE=2560 or 5425 

d = I IOAREA2=YES 

= Z IOAREA2=YES is not specified 

e = V RDONLY=YES and WORKA=YES 
= W WORKA=YES 
= Y RDONLY=YES 
= Z neither is specified 

Subset/Superset PRMOD Names 

Figure 3-43 shows the subsetting and supersetting 
allowed for PRMOD names. Two of the operands 
allow subsetting. For example, the module name 
IJDFCPIW is a superset of the module names 
IJDFCZIW and IJDFZZIW. No subsetting or superset- 
ting of PRMOD names is allowed for the 2560 or 
5424/ 5425. 

The iBM-supphes preassembled logic modules do 
not have TRC=YES. The system programmer can 
reassemble them with TRC=YES to support 3800 
table reference characters. Although the code that is 
generated for a module assembled with TRC=YES is 
different from the code that is generated for a mo- 
dule with TRC=NO, the module name is the same. If 
some, but not all PRMOD logic modules are reassem- 
bled this way, it may interfere with subsetting or 
supersetting. 



* * * * 
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+ Subsetting/supersetting permitted. 


* No subsetting/supersetting permitted. 



Figure 3-43. Subsetting and supersetting of PRMOD names. 
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DTFPT Macro 

A DTF entry is included for every paper tape input or output file that is processed by the program. The 
characteristics of a paper tape file are given in the DOS/VSE Macro User's Guide, as listed in the Preface. 



Applies to 


1 






Input 


Output 




X 


X 


M 


BLKSIZE = n 


Length of your I/O areas. 


X 


X 


M 


DEVADDR=SYSnnn 


Symbolic unit to be associated withi ttiis file. 


X 


X 


M 


I0AREA1 =xxxxxxxx 


Name of first I/O area. 


X 




O 


EOFADDR = xxxxxxxx 


Name of your end-of-file routine. 




X 





DELCHAR=Xnn' 


Delete character. 


X 


X 





DEVICE=nnnn 


(2671, 1017, 1018). If omitted, 2671 is assumed. 




X 





EORCHAR=Xnn' 


End-of-record character. (For RECFORM = UNDEF). 


X 


X 





ERROPT = xxxxxxxx 


(IGNORE, SKIP, or error routine name). Prevents job termina- 
tion on error records. 




X 





FSC AN = xxxxxxxx 


(For shifted codes). Name of your scan table used to select 
figure groups. 


X 







FTRANS= xxxxxxxx 


(For shifted codes). Symbolic address of your figure shift 
translate table. 


X 


X 





IOAREA2=xxxxxxxx 


Name of second I/O area. 


X 


X 





IOREG=(nn) 


Used with two I/O areas. Register (2-1 2) containing current 
record address. 




X 





LSC AN = xxxxxxxx 


(For shifted codes). Name of your scan table used to select 
letter groups. 


X 







LTRANS = xxxxxxxx 


(For shifted codes). Name of your letter shift translate table. 


X 


X 





MODNAME=xxxxxxxx 


For module names other than standard. 


X 


X 





OVBLKSZ=n 


Used if I/O records are compressed or expanded. 


X 


X 





RECFORM=xxxxxx 


(FIXUNB or UNDEF). If omitted, FIXUNB is assumed. 


X 


X 





RECSIZE=(nn) 


Register containing the record length. 


X 







SCAN=xxxxxxxx 


Name of your scan table for shift or delete character. 


X 


X 





SEPASMB=YES 


DTF is assembled separately. 


X 


X 





TRANS = xxxxxxxx 


Name of your table for code translation. 


X 







WLRERR =xxxxxxxx 


Name of wrong-length-record error routine. 



M= Mandatory 
0= Optional 

Figure 3-44. DTFPT macro operands. 

BLKSIZE=n: This operand specifies the length of 
the input or output area. The maximum block size is 
32,767 bytes. 

DELCHAR=X'nn': This operand specifies the 
configuration of the delete character and must be 
used for output files only, that is, when DEVICE=1018 
is specified. The constant x'nn' consists of two hexa- 
decimal digits. The delete character is used in the 
error recovery procedure, and you must specify the 
correct configuration in accordance with the number 
of tracks of the output tape, as follows: 

X' IF' for five tracks. 
X'3F' for six tracks. 
X'7F' for seven tracks. 
X'FF' for eight tracks. 



Note: The delete character is required only if the 1018 has the 
error correction feature. 



DEVADDR=SYSnnn: This operand specifies the 
logical unit (SYSnnn) associated with this file. An 
actual channel and unit are assigned to the unit by 
an ASSGN job control statement. The assgn state- 
ment contains the same symbolic name as 

DEVADDR. 

DEVICE= (2671 1101711018) : This operand is 
required only to specify the paper tape I/O device. If 
this entry is omitted, 2671 is assumed. 

EOFADDR=name: This operand specifies the 
name of your end-of-file routine. IOCS automatical- 



Chapter 3: Declarative Macros 3-67 



ly branches to this routine on an end-of-file condi- 
tion if the end-of-file switch is set on. The routine 
can execute any operation required for the end-of- 
file, issue the close or closer macro for the file, or 
return to IOCS by branching to the address in regis- 
ter 14. In the latter case, iocs reads in the next re- 
cord. The end-of-file condition cannot occur on the 
1018. 

EORCHAR=X'nn': This operand specifies the 
user-defined end-of-record (eor) character, where 
nn is two hexadecimal digits. It must be used for 
output files with undefined record format only. IOCS 
writes this character after the last character of the 
undefined record. 

ERROPT= {IGNORE|SKIP|name} : This ope- 
rand is specified if you do not want a job terminated 
when the standard recovery procedure cannot re- 
cover from a read or write error. If the ERROPT en- 
try is omitted and a read or write error occurs, IOCS 
terminates the job. 

For input files, ignore allows iocs to handle the 
record as if no errors were detected. If SKIP is speci- 
fied, IOCS skips the record in error and reads the 
next record. 

For output files with shifted codes, ERROPT can- 
not be specified. For unshifted codes, the options 
ERROPT=iGNORE and ERROPT=name can be speci- 
fied. IGNORE allows IOCS to handle the record as if 
no errors were detected. 

The ERROPT=SKiP option is ignored and causes 
IOCS to terminate the job. 

If two I/O areas are used, the CLOSE or CLOSER 
macro checks the last record, and the option 
ERROPT=name is treated as option 
ERROPT=IGNORE. 

For name, specify the symbolic address of your 
error routine that will process errors. On an error 
condition, IOCS reads or writes the complete record, 
including the error character(s), and then branches 
to the error routine. At the end of the error routine, 
return to IOCS by branching to the address in regis- 
ter 14. The next record is then read or written. You 
must not issue any GET or PUT macros for records in 
the error block. If the error routine contains any 
other IOCS macros, the contents of register 14 must 
be saved and restored. 

FSCAN=name: This operand must be included for 
every output file using a shifted code. Omit this 
operand for an input file. The operand specifies the 
name of a scan table in your program used to select 
groups of figures. This table must conform to the 



specifications of the machine instruction TRT. The 
entry in the table for each letter character must be 
the letter shift character, and all other entries must 
be hexadecimal zero. Any deviation from this re- 
sults in incorrect translation. 

FTRANS=name: This operand must be included 
for ever>' input file using a shifted code and is not 
permitted for output files. It specifies, the name of a 
figure shift table in your program. This table must 
conform to the specifications of the machine instruc- 
tion TR. 

IOAREAl=name: This operand specifies the name 
of an input or output area. 

IOAREA2=name: This operand specifies the name 
of a second input or output area. When this operand 
is specified, IOCS overlaps the I/O operation in one 
area with the processing of the record in the other. 

IOREG=(r): This operand must be included if two 
input or output areas are used. For input, it specifies 
the register into which IOCS puts the address of the 
logical record available for processing. For output, 
it specifies the register that contains the address of 
the area in which your program can build a record. 
Any register from 2 to 12 may be specified. 

LSCAN=name: This operand must be included for 
every output file using a shifted code and is not per- 
mitted for input files. It specifies the name of a scan 
table in your program used to select groups of let- 
ters. This table must conform to the specifications of 
the machine instruction trt. The entry in the table 
for each figure character must be the figure shift 
character, and all other entries must be hexadecimal 
zero. Any deviation from this results in incorrect 
translation. 

LTRANS=name: This operand must be included 
for every input file using a shifted code and is not 
permitted for output files. It specifies the name of a 
letter shift table in your program. This table must 
conform to the specifications of the machine instruc- 
tion TR. 

MODNAME=name: This operand specifies the 
name of the logic module used with the dtp table to 
process the file. If the logic module is assembled 
with the program, the MODNAME operand in this 
DTP must specify the same name as the PTMOD ma- 
cro. If the operand is omitted, IOCS generates stan- 
dard names for calling the logic module. 
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OVBLKSZ=n: For input files, this operand speci- 
fies the number of characters to be read (before 
translation and compression) to produce the number 
of characters specified in the BLKSIZE entry. 
OVBLKSZ is used only when scAN=name and 
RECF0RM=FIXUNB are both specified. If OVBLKSZ is 
omitted, IOCS assumes that the number of characters 
to be read is equal to the number specified in the 
BLKSIZE entry. The maximum value is 32,767 bytes. 

For output files, OVBLKSZ specifies the number of 
characters indicated in the BLKSIZE entry, plus the 
number of shift characters to be inserted. If the size 
of OVBLKSZ is large enough to allow the insertion of 
all the shift characters required to build the output 
record, a single WRITE operation results from a PUT 
macro. On the other hand, if the size of OVBLKSZ 
(which must be at least one position larger than 
BLKSIZE) does not permit the insertion of aU the 
shift characters, several WRITE operations result 
from a PUT macro. OVBLKSZ is used only when 
LSCAN and fscan are specified with the fixunb 
format. If OVBLKSZ is specified with undef format, 
it is ignored. 

RECFORM= (FIXUNB I UNDEF} : This operand 
specifies the record format for the file. Specify ei- 
ther format for shifted or unshifted codes. If the 
record format is FixUNB, this entry may be omitted. 

RECSIZE=(r): This operand specifies the number 
of a register (any one of 2 to 12) that contains the 
length of the input or output record. This entry is 
optional for input files. If present, IOCS loads the 
length of each record read into the specified register. 
If input files contain shift codes or other characters 
requiring deletion, IOCS loads the compressed record 
length into the specified register. 

For output files, this entry must be included for 
undefined records. Before translation, your program 
must load each record length into the designated 
register before issuing the PUT macro for the record. 

SCAN=name: This operand must be included for 
all input files using shifted codes. It may also be 
included if you wish to delete certain characters 
from each record. The SCAN entry specifies the sym- 
boUc name of a table provided by your program. 
This table must conform to the specifications of the 
machine instruction TRT. It must contain nonzero 
entries for aU delete characters and, where appropri- 
ate, for the figure and letter shift characters. 

The table entry for the figure shift character must 
be X'04'; for the letter shift character, the entry must 
be X'08'; delete entries must be X'OC. All other entries 



in the table must be X'OO'. Otherwise, incorrect trans- 
lation results and a program check may occur. 

The table must be large enough to hold the maxi- 
mum value of coding for the tape being processed; 
that is, 255 bytes for 8-track tape. This prohibits 
erroneous coding on the tape from causing a scan 
function beyond the limits of the scan table. 

SEPASMB=YES: Include this operand only if the 
DTFPT is assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and the filename to be defined as 
an ENTRY point in the assembly. If the operand is 
omitted, the assembler assumes that the dtf is being 
assembled with the problem program and no 
CATALR card is punched. 

TRANS=name: The TRANS operand specifies the 
symbolic name of a table provided within your pro- 
gram. This table must conform to the specifications 
of the machine instruction TR. For input files, in- 
clude this entry if a nonshifted code is to be translat- 
ed into internal system code. Omit the ftrans and 
LTRANS entries if this entry is present. If none of 
these three entries is present, no translation takes 
place. For output files, include this entry if the inter- 
nal system code is translated into a shifted or non- 
shifted code, depending on whether the FSCAN and 
LSCAN entries are present or omitted. 

WLRERR=name: This operand applies only to 
paper tape input files when recform=undef is 
specified. 

When IOCS finds a wrong-length record, it 
branches to the symbolic name specified in the 
WLRERR entry. If this entry is omitted and the 
ERROPT entry is included, IOCS considers the error 
uncorrectable and uses the ERROPT option specified. 
Absence of both erropt and wlrerr entries causes 
the wrong-length record to be accepted as a normal 
record. Wrong-length checking is not performed for 
fixed-length records because a fixed number of char- 
acters is read in each time. IOCS detects overlength 
undefined records when the incoming record fills 
the input area. The input area must, therefore, be at 
least one position longer than the longest record 
anticipated. 

At the end of the wlrerr routine, return to IOCS 
by branching to the address in register 14. The next 
IOCS read operation will normally cause the remain- 
der of the overlength, undefined record to be read. 
If any other IOCS macros are included in the record- 
length error routine, the contents of register 14 must 
be saved and restored. 
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Note: A wrong-length condition appears during the first read 
operation on a 1017 if the combined length of the tape leader and 
the first record is greater than the length of the longest record 
anticipated (the length specified in BLKSIZE). 
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PTMOD Macro 

Listed here are the operands you can specify for ptmod; Figure 3-45 shows the only possible combination of 
these operands and describes the resultant modules. 



Operand * 


Resulting Module 


DEVICE= 


RECFORM= 


SCAN = 


TRANS= 


2671 ** 


FIXUNB * * 






Does not handle translation or shift or delete characters 


2671 ** 


FIXUNB ** 




YES 


Handles translation of unshifted codes, but not delete charac- 
ters 


2671 ** 


FIXUNB ** 


YES 




Handles shift and delete characters for records of fixed un- 
blocked format 


2671 ** 


FIXUNB ** 


YES 




2671 ** 


UNDEF 


YES 




Handles shift and delete characters for records of undefined 
format 


1017 


FIXUNB ** 






Does not handle translation or shift or delete characters 


1017 


FIXUNB ** 




YES 


Handles translation of unshifted codes, but no delete charac- 
ters 


1017 


FIXUNB ** 


YES 




Handles shift and delete characters for records of fixed un- 
blocked format 


1017 


UNDEF 


YES 




Handles shift and delete characters for records of undefined 
format 


1018 


FIXUNB ** 




YES 


Handles translation of unshifted codes, if specified in DTFPT, 
for records of fixed unblocked format 


1018 


FIXUNB ** 






1018 


UNDEF 






Handles translation of unshifted codes, if specified in DTFPT, 
for records of undefined format 


1018 


UNDEF 




YES 


1018 


FIXUNB ** 


YES 




Handles shift characters for records of fixed unblocked format 


1018 


UNDEF 


YES 




Handles shift characters for records of undefined format 


* In all cases, SEPASMB = YES may either be specified or omitted 

* * Specified explicitly or by default 



Figure 3-45. PTMOD operand combinations. 

DEVICE= [2671 1 1017| 1018} : Required only to 
specify an I/O device other than 267 1 used by the 
module. Any dtp used with the module must have 
the same operand. 2671 is assumed if this operand is 
omitted. 

RECFORM= (FIXUNB I UNDEF): Required 
only if the operand scan=yes is present. If records 
of undefined format using the SCAN option are 
translated, specify the undef parameter. If records 
of fixed unblocked format are translated, the 
FIXUNB parameter may be specified or omitted. 

SCAN=YES: Required for records containing shift 
characters and/or characters that are automatically 
deleted by IOCS. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and defines the module name as an ENTRY 
point in the assembly. If the operand is omitted, the 
assembler assumes that the module is being assem- 



bled with the DTP and the problem program and no 
CATALR card is punched. 

TRANS=YES: Required only if records using an 
unshifted code are translated and if the operand 
SCAN=YES is not specified. 

Standard PTMOD Names 

Each name begins with a 3 -character prefix (IJE) 
and continues with a 5 -character field corresponding 
to the options permitted in the generation of the 
module. 

PTMOD name =IJEabcde 

a = S SCAN=YES 

= Z SCAN=YES is not specified 

b = T TRANS=YES (SCAN= YES is not specified) 
= Z TRANS=YES is not specified 

c = P RECPORM=FIXUNB, and SCAN=YES 
= U RECFORM^UNDEP, and SCAN=YES 
= Z SCAN=YES is not specified, and/or DEVICE= 10 18 

d = 1 DEVICE=1017 
= 2 DEVICE=1018 . 
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= Z DEVICE=267 1, or ifthis entry is omitted 
e = Z always 

Subset/Superset PTMOD Names 

Figure 3-46 shows the PTMOD names. No subsetting 
or supersetting is allowed. 



* 


* * * 


I J E Z 


Z Z Z Z 


Z 


T Z Z 


S 


Z F Z 


S 


Z U Z 


Z 


Z Z 1 


Z 


T Z 1 


s 


Z F 1 


s 


Z U 1 


s 


Z Z 2 


z 


T Z 2 


* No subsetting/supersetting permitted. 



Figure 3-46. Subsetting and supersetting of PTMOD names. 
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DTFSD Macro 

The DTFSD macro defines sequential (consecutive) processing for a file contained on a dasd. Only IBM 
standard label formats are processed. 



Applies to 








Input 


Output 


Work 




X 


X 


X 


M 


BLKSIZE = nnnn 


Length of one I/O area, in bytes 


X 




X 


M 


EOFADDR = xxxxxxxx 


Name of your end-of-file routine 


X 


X 




M/0 


I0AREA1 =xxxxxxxx 


Name of first I/O area. Optional for some files in Control Inter- 
val format. 


X 


X 


X 





CISIZE = nnnnn 


Size of FBA Control Interval. If omitted and DEVICE = FBA, 
default is 0. 


X 


X 


X 





CONTROL=YES 


CNTRL macro is used for this file 






X 





DELETFL = NO 


CLOSE, CLOSER macro is not to delete format-1 and format-3 
labels for work file 


X 


X 


X 





DEVADDR = SYSnnn 


Symbolic unit required only when not provided on an EXTENT 
statement 


X 


X 


X 





DEVlCE = nnnn 


(231 1 , 2314, 3330, 3340, 3350, ^g^. Specify any device for 
a 3330-1 1 or 3350. Specify FBA for 331 or 3370. If omitted, 
231 1 is assumed. 


X 


X 


X. 





ERREXT=YES 


Additional error and ERET are desired. Specify ERROPT also 


X 


X 


X 





ERROPT=xxxxxxxx 


(IGNORE, SKIP, or name of error routine). Prevents job termi- 
nation on error records. Do not use SKIP for output files 


X 


X 







FEOVD=YES 


Forced end of volume for disk is desired 


X 




X 





HOLD = YES 


Employ the track hold function 


X 


X 







I0AREA2 =xxxxxxxx 


If two I/O areas are used, name of second area 


X 


X 







IOREG=(nn) 


Register number. Use only if GET or PUT does not specify 
work area or if two I/O areas are used. Omit WORK A 


X 


X 







LABADDR =xxxxxxxx 


Name of your routine to check /write user-standard labels 


X 


X 


X 





MODNAME = xxxxxxxx 


Name of SDMODxx logic module for this DTF. If omitted, IOCS 
generates standard name. Ignored if DEVICE = FBA is speci- 
fied. 






X 





NOTEPNT = xxxxxxx 


(YES or POINTRW). YES if NOTE/POINTR/POINTW/POINTS 
used. POINTRW if only NOTE/POINTR/POINTW used 




X 


X 





PWRITE=YES 


For FBA files only, specify for a physical write of each logical 
block. 


X 


X 


X 





RDONLY=YES 


Generates a read-only module. Requires a module save area 
for each task using the module 


X 


X 


X 





RECFORM = xxxxxx 


(FIXUNB, FIXBLK, VARUNB, VARBLK, SPNUNB, SPNBLK, or 
UNDEF). For work files use FIXUNB or UNDEF. If omitted, 
FIXUNB is assumed 



M = Mandatory 
0=Optional 

Figure 3-47. DTFSD macro operands (Part 1 of 2). 



Chapter 3: Declarative Macros 3-73 



Applies to 








Input 


Output 


Work 




X 


X 







RECSIZE=nnnnn 


If RECFORM = FIXBLK, number of characters in record. If 
RECFORM=SPNUNB, SPNBLK, or UNDEF, register number. 
Not required for other records 


X 


X 







SEPASMB=YES 


DTFSD is to be assembled separately. 


X 


X 







TRUNCS=YES 


RECFORM = FIXBLK or TRUNC macro used for this file 


X 


X 


X 





TYPEFLE=xxxxxx 


(INPUT. OUTPUT, or WORK). If omitted, INPUT is assumed 


X 




X 





UPDATE=YES 


Input file or work file is to be updated 




X 







VARBLD=(nn) 


Register number if RECFORM=VARBLK and records are built 
in the output area. Omit if WORKA=YES 




X 


X 


O 


VERIFY=YES 


Check disk records after they are written. 


X 






O 


WLRERR=xxxxxxxx 


Name of your wrong-length-record routine 


X 


X 







WORKA=YES 


GET or PUT specifies work area. Omit lOREG. Required for 
RECFORM = SPNUNB or SPNBLK. 



M = Mandatory 
= Optional 

Figure 3-47. DTFSD macro operands (Part 2 of 2). 

BLKSIZE=n: Enter the length of the I/O area. If 
the record format is variable or undefined, enter the 
length of the I/O area needed for the largest block of 
records. 

For output files, the first 8 bytes of the I/O area 
(whose address is specified in the ioareai operand) 
must be allotted for IOCS to construct a count field. 

The BLKSIZE parameter on the DLBL statement 
overrides the DTFSD BLKSIZE specification if the 
device assigned is a 3330-1 1 or 3350, and if 
RECFORM=xxxBLK. For an output file, the records are 
blocked according to the size specified by the appro- 
priate BLKSIZE parameter (from the DLBL statement 
if it was specified; othenvisc from the DTFSD). For 
an input file, the BLKSIZE specification must match 
the format of the data as it resides on the disk. 

To use the DLBL BLKSIZE parameter, your pro- 
gram must: 

• Run on a system with RPS support sysgened. 
The logic module must be in the SVA, or there 
must be enough space available in the SVA to 
load the logic module. 

• Have GETVis space for an rps dtf extension 
and new buffers. 

• Specify DTFSD RECFORM=xxxBLK. 

If there is no RPS support, if the file is not on a 
3330-1 1 or 3350, if the getvis fails, or if the file is 
not a blocked data file, the job is canceled. For 
blocked files with fixed length records, BLKSIZE 



must be a multiple of RECSIZE or the job will be 
canceled. 

When DEVICE=FBA, or if clslZE=n is specified, 
BLKSIZE determines logical block size. For fba 
DASD, maximum value is 32761 (that is, seven bytes 
less than maximum CISIZE). The BLKSIZE value for 
output files must include eight bytes for a count area 
to provide compatibiUty between FBA and CKD 

DASD. 

CISIZE=n: This operand specifies the control in- 
terval size for an fba device assigned to a non- 
system file logical unit. If assigned to a system file 
(SYSRDR, SYSiPT, SYSLST, or syspch), the operand is 
ignored. The value n must be a multiple of the FBA 
block size and, if greater than 8K, must be a multiple 
of 2K. The maximum value is 32768 (32K) except 
when assigned to SYSLST or SYSPCH, when the maxi- 
mum is 30720 (30K). 

If DEYICE=FBA is Specified, and CisiZE is omitted, 
CISIZE=0 is assumed. Control Interval size may be 
overridden for an output file at execution time by 
specifying the cisiZE parameter on the DLBL control 
statement. For an input file, the CISIZE value in the 
format- 1 label is used. 

CONTROL=YES: This operand is specified if a 
CNTRL macro is to be issued for the file. A ccw is 
generated for control commands. For an FBA file, 
this operand is ignored. 
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DELETFL=NO: Specify this operand if the CLOSE 
or CLOSER macro is not to delete the format- 1 and 
format-3 label for a work file. The operand applies 
to work files only. 

DEVADDR=SYSnnn: This operand must specify 
the symbolic unit associated with the file if an extent 
is not provided. A job control EXTENT statement is 
not required for single-volume input files. If an 
EXTENT statement is provided, its specification over- 
rides any devaddr specification. SYSnnn represents 
an actual I/O address, and is used in the ASSGN job 
control statement to assign the actual I/O device 
address to this file. 

DEVICE= (2311 |2314|3330| 
3340|3350|FBA}: 

This operand is included to specify the device on 
which the file is located. If no device is specified, 
23 11 is assumed. If an fba device is ASSGNed to the 
file, DEVICE= is ignored. 

For devices supported by DOS/VSE and not in- 
cluded in the above operand specification, specify 
device codes as listed in Figure 3-48. 

EOFADDR=name: This operand specifies the 
name of your end-of-file routine. IOCS automatically 
branches to this routine on an end-of-file condition. 
In this routine, you can perform any operations re- 
quired at end of file (you generally issue the CLOSE 
or CLOSER macro). 

ERREXT=YES; This operand enables your 
ERROPT or WLRERR routine to return to SDMOD by 
means of the ERET macro. It also enables unrecover- 
able I/O errors (such as "record not found") occur- 
ing before a data transfer takes place to be indicated 
to your program. For ERREXT facilities, the erropt 
operand must be specified. To take fuU advantage 
of this option, code the ERROPT=name parameter. 



ERREXT=YES is assumed if device=fba is speci- 
fied, or if an FBA device is ASSGNed to the file. 

ERROPT= {IGNORE|SKIP|name}: This ope- 
rand is specified if a job is not to be terminated 
when a read or write error cannot be corrected in the 
disk error routines. The disk error routines normally 
retry failing I/O operations several times before con- 
sidering the error unrecoverable. Once the error is 
considered unrecoverable, the job is terminated un- 
less the ERROPT operand is specified. The functions 
of the parameters are explained below. 

ignore 

The error condition is ignored. The records are 
made available for processing. When reading 
spanned records, the whole spanned record or 
block of spanned records is returned, rather 
than just the one physical record in which the 
error occurred. 

On output, the physical record or control inter- 
val in which the error occurred is ignored as if 
it were written correctly. If possible, any re- 
maining spanned record segments are written. 



SKIP 



No records in the error block or control inter- 
val are made available for processing. The next 
block or control interval is read from the disk, 
and processing continues with the first record 
of that block. When reading spanned records, 
the whole spanned record or block of spanned 
records is skipped, rather than just one physi- 
cal record. 

On an update=yes file, the physical record or 
control interval in which the error occurred is 
ignored as if it were written correctly. If possi- 
ble, any remaining spanned record segments 
are written. 



DEVICE = 
specification 


Device to be ASSGNed 


2311 


2314 


2319 


3330-1,2* 


3330-1 1 * * 


3340, 35IVIB 


3340, 70MB 


3350 


3310, 3370 


Default 


X 








X 






X 


X 


2311 


X 








X 






X 


X 


2314 




X 


X 




X 






X 


X 


3330 








X 


X 






X 


X 


3340 










X 


X 


X 


X 


X 


3350 










X 






X 


X 


FBA 


















X 



* Also 3350 in 3330-1 compatibility mode. 

* * Also 3350 in 3330-1 1 compatibility mode. 

Figure 3-48. DEVICE= specifications for DTFSD. 
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name 

IOCS branches to your error routine named by 
this parameter. In this routine you can process 
or make note of the error condition as desired. 

FEOVD=YES: This operand is specified if a forced 
end of volume for disk feature is desired. It forces 
the end-of-volume condition before physical end of 
volume occurs. When the FEOVD macro is issued, 
the current volume is closed, and I/O processing 
continues on the next volume. 

HOLD=YES: This operand may be specified only 
if the track hold function was specified at system 
generaiion time and if it is employed when a data 
file or a work file is referenced for updating. 

IOAREAl=name: This operand specifies the sym- 
bolic name of the I/O area used by the file. IOCS 
either reads or writes records using this area. If 
DEVICE=FBA is Specified, this operand is not manda- 
tory. It is ignored if W0RKA=YES is specified. It is 
optional for input files if iOREG=(r) is specified. It is 
also optional for output files with fixed length re- 
cords without truncation if lOREG=(r) is specified, 
but is required for all other fba files. 

For variable-length or undefined records, this 
area must be large enough to contain the largest 
block or record. 

IOAREA2=name: If two I/O areas are used by GET 
or PUT, this operand is specified. When variable 
length records are processed, the size of the I/O area 
must include four bytes for the block size. For out- 
put files, the I/O area must include eight bytes to 
build a count field. 

IOREG=(r): This operand specifies the general 
purpose register (any of 2 to 12) in which IOCS puts 
the address of the logical record that is available for 
processing. At open time, for output files, IOCS puts 
into the register specified the address of the area 
where you can build a record. The same register 
may be used for two or more files in the same pro- 
gram, if desired. If this is done, the program must 
store the address supplied by IOCS for each record. 

This operand must be specified if blocked input 
or output records are processed in one I/O area, or if 
two I/O areas are used and the records are processed 
in both I/O areas. 

For an FBA file, if lOAREA(s) are not specified, the 
register specified by lOREG will point directly to 
data in the control interval buffer. 

LABADDR=name: Specifies the name of the rou- 
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tine in which you process your own labels. 

MODNAME=name: This operand may be used to 
specify the name of the logic module that will be 
used with the DTF table to process the file. If the 
logic module is assembled with the program, 
MODNAME must specify the same name as the 
SDMODxx macro. 

This operand is ignored if device=fba is speci- 
fied. If this operand is omitted for other than fba 
files, standard names are generated for calling the 
logic module. If two DTF macros call for different 
functions that can be handled by a single module, 
nnlv Qng module is called. 



NOTEPNT= {POINTRW|YES}: The parameter 
POINTRW is Specified if a NOTE, pointr, or POINTW 
macro is issued for the file. If the parameter YES is 
specified, NOTE, POINTR, pointw, and points mac- 
ros may be issued for the file. 

PWRITE=YES: This operand is specified if for- 
matting output operations (put for data files or 
WRITE SQ for work files) are to cause a physical 
write for each logical block. If omitted, the physical 
write takes place only when the control interval 
buffer is fuU. 

RDONLY=YES: This operand is specified if the 
DTF is used with a read-only module. Each time a 
read-only module is entered, register 13 must con- 
tain the address of a 72-byte doubleword-aligned 
save area. Each task should have its own uniquely 
defined save area. When an imperative macro 
(except open, openr, or lbret) is issued, register 13 
must contain the address of the save area associated 
with the task. The fact that the save areas are unique 
for each task makes the module reentrant (that is, 
capable of being used concurrently by several tasks). 

If an ERROPT or wlrerr routine issues I/O mac- 
ros using the same read-only module that caused 
control to pass to either error routine, your program 
must provide another save area. One save area is 
used for the normal I/O operations, and the second 
for I/O in the ERROPT or wlrerr routine. Before 
returning to the module that entered the error rou- 
tine, register 13 must be set to the save area address 
originally specified for the task. 

As all control interval format logic modules are 
reentrant and read-only, this operand is ignored if 
device=fba is specified. As the control interval 
format and RPS logic modules support dtfs with 
either read-only or non-read-only modules, no save 
area need be established. 



If the operand is omitted for other than FBA files, 
the module generated is not reenterable and no save 
area need be established. 

RECFORM= (FIXUNB |FIXBLK|VARUNB| 
VARBLK|SPNUNB1SPNBLK| 
UNDEF}: 

This operand specifies the type of records for input 
or output. Enter one of the following parameters: 

FIXUNB For fixed-length unblocked records 

FIXBLK For fixed-length blocked records 

VARUNB For variable-length unblocked records 

VARBLK For variable-length blocked records 

SPNUNB For spanned variable-length unblocked records 

SPNBLK For spanned variable-length blocked records 

UNDEF For undefined records 

If RECFORM=SPNUNB or RECFORM=SPNBLK is Speci- 
fied and RECSlZE=(r) is not specified, an assembler 
diagnostic (MNOTE) is issued, and register 2 is as- 
sumed. If wORKA=YES is omitted, an mnote is is- 
sued and WORKA=YES is assumed. If recform is 
omitted, FIXUNB is assumed. 

RECSIZE= (nl(r)} : For fixed-length blocked re- 
cords, RECSIZE is required. It specifies the number 
of characters in each record. 

Register notation must be used when processing 
spanned or undefined records. When processing 
undefined records and variable-length spanned re- 
cords, RECSIZE is required for output files and is 
optional for input files. The operand is invaUd for 
work files. It specifies a general register (any one of 
2 to 12) that contains the length of the record. On 
output, you must load the length of each record into 
the designated register before issuing a PUT macro. 
If specified for input, iocs provides the length of the 
record transferred to virtual storage. 

SEPASMB=YES: Include this operand only if the 
DTFSD is assembled separately. This causes a 
CATALR card with the filename to be punched ahead 
of the object deck and the filename to be defined as 
an ENTRY point 'in the assembly. If the operand is 
omitted, the assembler assumes that the DTF is being 
assembled with the problem program and no 
CATALR card is punched. 

TRUNCS=YES: This operand is specified if 
FIXBLK DASD files contain short blocks embedded 
within an input file or if the input file was created 
with a module that specified TRUNCS. This entry is 
also specified if the trunc macro is issued for a 
FIXBLK output file. 

TYPEFLE={INPUT|OUTPUT|WORK}: Use 



this operand to indicate whether the file is an input 
or output file. If work is specified, a work file is to 
be used. If INPUT or output is specified, the GET or 
PUT macros, respectively, can be used. If work is 
specified, the read and write, note and pointx, 
and CHECK macros can be used. 

UPDATE=YES: This operand must be included if 
the DASD input or work file is updated - that is, if 
disk records are read, processed, and then re-written 
in the same disk record locations from which they 
were read, close writes any remaining records in 
sequence onto the disk. 

This operand is invalid for a file on an fba dasd 
assigned to a system logical unit (sysrdr, sysipt, 
SYSLST, or SYSPCH). If a PUT is attempted to an 
input file, the job will be terminated. 

VARBLD=(r): Whenever variable-length blocked 
records are built directly in the output area (no work 
area specified), this entry must be included. It speci- 
fies the number (r) of a general-purpose register 
(any one of 2 to 12), which will always contain the 
length of the available space remaining in the output 
area. 

iocs calculates the space still available in the 
output area, and supplies it to you in the designated 
register after the PUT macro is issued for a variable- 
length record. You then compare the length of your 
next variable-length record with the available space 
to determine if the record fits in the area. This check 
must be made before the record is built. If the record 
does not fit, issue a TRUNC macro to transfer the 
completed block of records to the file. Then, the 
present record is built at the beginning of the output 
area in the next block. 

VERIFY=YES: This operand is included if you 
want to check the parity of disk records after they 
are written. If this operand is omitted, any records 
written on a disk are not verified. 

WLRERR=name: This operand applies only to 
disk input files. It does not apply to undefined re- 
cords. WLRERR specifies the symboUc name of your 
routine to receive control if a wrong-length record is 
read. 

If the WLRERR operand is omitted but a wrong- 
length record is detected by iocs, one of the follow- 
ing conditions results: 

• If the ERROPT entry is included for this file, the 
wrong-length record is treated as an error block 
and handled according to your specifications 
for an error (ignore, skip, or name of error 
routine). 
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• If the ERROPT entry is not included, the error is fy this operand. You must set up the work area in 

ignored. storage. The address of the work area, or a general- 

TTjr-j J .^uijf- 4. purpose register which contains the address, must be 

Undefined records are not checked for mcorrect *^ . ^ , . ° , ^ 

record length. The record is truncated when the ^P^^^^^^^ "^ ^^""^ ""^^^ ""' ^^'"^ "^^^f • ^^^ ^ ^^^ f 



PUT macro, iocs moves the record to, or from, the 
specified work area. WORKA=YES is required for 
WORKA= YES: If I/O records are processed, or ^^^UNB and SPNBLK. When this operand is specified 



BLKSIZE Specification is exceeded. 

WORKA=YES: If I/O records ai . , , _. 

built, in work areas instead of in the I/O areas, sped- ^""^ ^ ^'^^^ ^he lOREG operand must be omitted. 
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SDMODxx Macro 

Sequential DASD files on FBA devices do not need 
SDMODxx logic module macros to be specified for 
them because preassembled re-entrant logic modules 
are loaded into the sva at IPL time and are available 
to all partitions, as needed, for FBA support. These 
modules are functional subsets. An SDMODxx mo- 
dule associated with a problem program is ignored if 
the file is assigned to an fba device. 

Sequential DASD module generation macros dif- 
fer from other iocs module generation macros. The 
file characteristics are separated into ten categories, 
and each category has a unique macro associated 
with it (see Figure 3-49). 



Macro 


Module Generated 


SDMODFI 


Sequential DASD Module, Fixed-length 
records', Input file 


SDMODFO 


Sequential DASD Module, Fixed-length 
records', Output file 


SDMODFU 


Sequential DASD Module, Fixed-length 
records', Update file 


SDMODVI 


Sequential DASD Module, Variable- 
length records (including spanned 
records)^. Input file 


SDMODVO 


Sequential DASD Module, Variable- 
length records (including spanned 
records)^. Output file 


SDMODVU 


Sequential DASD Module, Variable- 
length records (including spanned 
records)^. Update file 


SDMODUI 


Sequential DASD Module, Undefined 
records^. Input file 


SDMODUO 


Sequential DASD Module, Undefined 
records-'. Output file 


SDMODUU 


Sequential DASD Module, Undefined 
records^ Update file 


SDMODW 


Sequential DASD Module, Work file"* 


' RECFORM = FIXUNB or FIXBLK in DTFSD 

2 RECFORM=VARUNB, VARBLK, SPNUNB, or SPNBLK 

in DTFSD 

3 RECFORM = UNDEF in DTFSD 

^ RECFORi^ = FIXUNB or UNDEF in DTFSD 



Figure 3-49. SDMOD macros. 

The macro operation code and the keyword ope- 
rands define the characteristics of the module. Mo- 
dules for a specific file can thus be generated more 
quickly than if there were only one macro. A mo- 
dule name may be contained in the name field of the 
macro. The macro operation code is contained in the 
operation field (SDMODFI, for example). The ope- 
rands are contained in the operand field. The ope- 
rands for the ten macros are summarized in Figure 
3-50 and explained below. 



The control interval format logic lodules assume 
the value YES for all the following operands except 
RECFORM (where SPNBLK is assumed) and RPS. 

CONTROL=YES: This operand is specified if a 
CNTRL macro is issued for the file. This entry applies 
to all SDMODxx macros. The module also processes 
any DTF in which the CONTROL parameter is not 
specified. 

ERREXT=YES: Include this operand if non-data- 
transfer errors are returned to an ERROPT routine in 
your program or if the eret macro is used with the 
DTF and module. If errext is specified, ERROPT 
must also be specified. 

ERROPT=YES: This operand applies to all 
SDMODxx macros. It is included if the module han- 
dles any of the error options for an error block. Log- 
ic is generated to handle any of the three options 
(IGNORE, SKIP, or name) regardless of which option 
is specified in the DTF. The module also processes 
any DTF in which the ERROPT operand is not speci- 
fied. 

If this operand is not included, your program is 
canceled whenever any unrecoverable error except a 
wrong-length record error (which LIOCS ignores) is 
encountered. 

FEOVD=YES: This operand is specified if the 
forced end of volume for disk feature is desired. It 
allows the program to force an end of volume condi- 
tion before physical end of volume occurs. When the 
FEOVD macro is issued, the current volume is closed, 
and I/O processing continues on the next volume. 

HOLD=YES: This operand applies only to update 
files (SDMODFU, SDMODVU, and sdmoduu) and 
work files (SDMODW). The operand is included if the 
track hold function is employed. Any DTF used with 
the module must have the same operand. 

NOTEPNT= {POINTRW|YES} : This operand 
applies to SDMODW (work files) only. It is included 
if any NOTE, POINTR, POINTS, or POINTW macros are 
used within the module. If the operand specifies 
POINTRW, logic to handle only NOTE, POINTR, and 
POINTW is generated. 

If YES is specified, the routines to handle note, 
POINTR, POINTS, and POINTW are generated and any 
files that specify notepnt=pointrw in the DTF are 
processed. 

RDONLY=YES: This operand causes a read-only 
module to be generated. Whenever this operand is 
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Operand 


Required 


Comments 


CONTROL=YES 


If the CNTRL macro is to be issued for the file. 


Applies to all SDMODs. 


ERREXT=YES 


If the module returns non-data-transfer errors or is 
used with the ERET macro. 


Applies to all SDMODs. 


ERROPT=YES 


If the module is to handle error options for an er- 
ror block. 


Applies to all SDMODs. 


FEOVD=YES 


If the FEOVD macro is to be issued for the file. 


Applies to all SDMODs except 
SDMODW. 


HOLD = YES 


If the track hoid lunction is to be erriployed. 


Applies to update and work file logic 
modules. 


NOTEPNT= {POINTRW|YES} 


If NOTE, POINTR, POINTS, or POINTW macros 
are to be issued for the file. 


This parameter applies to SDMODW 
only. The operand POINTRW generates 
logic for NOTE, POINTR, and POINTW. 
The operand YES generates logic for all 
macros. 


RDONLY=YES 


If a read-only module is to be generated. 


Applies to all SDMODs. 


RECFORM= {SPNUNB|SPNBLK} 


If unblocked or blocked spanned records are to be 
processed. 


Applies to SDMODVI, SDMODVO, and 
SDMODVU only. 


RPS=SVA 


If RPS support is desired. 


To assemble the RPS logic modules. 


SEPASMB=YES 


If the module is assembled separately from the 
DTP. 


Applies to ail SDMODs. 


TRUNCS=YES 


If the TRUNC macro is to be issued for the file. 
Assumed for output files consisting of variable- 
length blocked records. 


Applies to all SDMODs for fixed-length 
records. 


UPDATE = YES 


If SDMODW is to process the WRITE UPDATE 
macro. 


Applies to SDMODW only. 



Figure 3-50. SDMODxx operands. 

Specified, any DTP used with the module must have 
the same operand. 

RECFORM= (SPNUNBISPNBLK): This ope- 
rand is required only for SDMODVI (input files), 
SDMODVO (output files), and SDMODVU (update 
files) if RECFORM=SPNUNB OF SPNBLK is Specified in 
the DTF macro. If RECFORM is specified incorrectly, 
an assembler diagnostic (MNOTE) is issued, and the 
module generation is terminated. 

RPS=SVA: This operand causes the RPS logic mo- 
dules to be assembled. When this operand is used, 
only superset modules are generated. 

SEPASMB=YES: Include this operand only if the 
module is assembled separately. This causes a 
CATALR card with the module name (standard or 
user-specified) to be punched ahead of the object 
deck and the module name to be defined as an 
ENTRY point in the assembly. If the operand is omit- 
ted, the assembler assumes that the module is being 
assembled with the DTF and the problem program 
and no catalr card is punched. 

TRUNCS=YES: This operand applies to all 
SDMOD macros for fixed-length records. It generates 
a logic module which can handle the TRUNC macro. 
This operand is assumed for varblk output files. 



This operand is ignored if specified for varblk 
input or update files. It must be specified if any 
FIXBLK DASD files (processed by the module) con- 
tain short blocks embedded within them, if the input 
file was created with a module that specified 
TRUNCS, or if the DTF was specified with 
RECFORM=UNDEF. The module cannot process any 
DTF for fixed-length records in which the TRUNCS 
operand is not specified. 

UPDATE=YES: This operand applies to the 
SDMODW only. It is assumed for SDMODFU, 
SDMODUU, and SDMODVU and generates a logic 
module which can handle the WRITE update macro 
with work files. 

Standard SDMOD Names 

Each name begins with a 3 -character prefix (IJG) 
and continues with of a 5 -character field corre- 
sponding to the options permitted in the generation 
of the module. 

In SDMOD there are two module classes: 

• Those which handle GET/PUT functions 

• Those which handle read/write, 
NOTE/POiNTx, and CHECK functions (work 
files). 
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Name List for GET/PUT Type Modules 

SDMODxx name = IJGabcde 

a = C SDMODFx specifies HOLD=YES 

= F SDMODFx does not specify HOLD=YES 

= R SDMODUx specifies HOLD=YES 

= U SDMODUx does not specify HOLD=YES 

= P SDMODVx specifies HOLD=YES and 
RECFORM=SPNBK|SPNUNB 

= Q SDMODVx does not specify HOLD=YES and speci- 
fies RECFORM=SPNBLKlSPNUNB 

= S SDMODVx specifies HOLD=YES 

= V SDMODVx does not specify HOLD=YES 

b = U SDMODxU 
= I SDMODxI 
= O SDMODxO 
= W SDMODxI, RPS=SVA 
= X SDMODxO, RPS=SVA 
= Y SDITODxU, RPS=SVA 

c = C ERROPT=YES and ERREXT=YES, RPS=SVA 
= E ERROPT=YES 
= Z neither is specified 

d = M TRUNCS=YES and FEOVD=YES (see Note 1 be- 
low) 

= T TRUNCS=YES (see Note 1 below), RPS=SVA 

= W FEOVD=YES (see Note 2 below), RPS=SVA 

= Z neither is specified (see Note 2 below) 

e = B CONTROL=YES and RDONLY=YES, RPS=SVA 

= C CONTROL=YES 

= Y RDONLY=YES 

= Z neither is specified 

Notes: 

1. Generated only for SDMODFx. 

2. If generated for SDMODVO, TRUNC logic is available. 

Name List for Workfile Type Modules 
(TYPEFLE=WORK) 

SDMODxx name = IJGabcde 

a = T HOLD=YES 

= W HOLD=YES not specified 

b = C ERROPT=YES and ERREXT=YES 
= E ERROPT=YES 
= Z neither is specified 



c = N NOTEPNT=YES 

= R NOTEPNT=POINTRW 

= Z NOTEPNT is not specified 

d = C CONTROL=YES 

= Z CONTROL= YES is not specified 

e = T RDONLY=YES and UPDATE=YES 

= U UPDATE=YES 

= Y RDONLY=YES 

= Z neither is specified 

Subset/Superset SDMOD Names 

Figure 3-51 illustrates the subsetting and superset- 
ting allowed for SDMOD names. For the GET/PUT 
type modules, four parameters allow supersetting. 
For example, in the get/put type module, the mo- 
dule IJGFUETC is a superset of a module with the 
nameoflJGFUZTZ. 



For GET/PUT Type 


i Modules: 
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+ + 
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For Workfile Type 


Modules: 
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+ Subsetting/supersetting permitted. 


* No subsetting/supersetting permitted. 



Figure 3-51. Subsetting and supersetting of SDMOD names. 
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Chapter 4: Imperative Macros 



CCB Macro 



Name Operation Operand 



blocknameCCB 



SYSnnn,command-list-name 
[,X'iinnn'][,senseaddress] 



A CCB (command control block) macro must be 
specified in your program for each I/O device con- 
trolled by physical IOCS macros. The CCB (see Fig- 
ure 4-1) is necessary to communicate information to 
physical IOCS so that it can perform desired opera- 
tions (for example, notifying your program of print- 
er channel 9). The CCB also receives status informa- 
tion after an operation and makes this available to 
your program. You should ensure proper boundary 
alignment of the CCB if this is necessary for your 
program. 

Note: In some applications, it may be preferable to use an lORB 
(I/O Request Block) in place of a CCB. Do this by specifying 
either an lORB or GENIORB macro. 

blockname: The CCB macro must be given a 
symbolic name (blockname). This name can be used 
as the operand in the EXCP and wait macros which 
refer to the CCB. 

SYSnnn: This operand specifies the symbolic unit 
for the actual I/O unit with which this cCB is associ- 
ated. The actual I/O unit can be assigned to the sym- 



bolic unit by an ASSGN job control statement. 

command-list-name: This operand specifies the 
symbolic name of the first ccw used with a CCB. 
This name must be the same as the name specified 
in the assembler ccw statement that constructs the 

CCW. 

X'nnnn'; A hexadecimal value used to set the CCB 
user option bits. Column 5 of Figure 4-2 gives the 
value used to set a user option bit 'on'. If more than 
one bit must be set, the sum of the values is used. 

senseaddress: This operand, when supplied, 
indicates user error recovery (see Figure 4-2, byte 2, 
bit 7) and generates a ccw for reading sense inform- 
ation as the last field of the CCB. The name field 
(sense address) of the area that you supply must 
have a length attribute assigned of at least one byte. 
Physical IOCS uses this length attribute in the ccw to 
determine the number of bytes of sense information 
you desire. 

CCB Format 

From the above specifications, the macro sets up an 
area of either 16 bytes or 24 bytes. For the layout of 
this area and its contents see Figure 4- 1 . 
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Bytes 



16 



^ 



Residual count 



reserved 



O 



Transmission 
information 



CCW address 



o 



^ 



<h 



CSW status 
\ 



Type code 



reserved CCW address in CSW 



optional sense CCW 
J__ 1 u 







After a record has been transferred, IOCS places the 
residual count from the CSW into these two bytes. By 
subtracting the residual count from the original count in 
the CCW, your program can determine the length of the 
transferred record. The field is set to zero for negative 
values. 

Used for transmission of information between physical 
IOCS and your program. For detailed information on the 
use and purpose of the individual bits in this field, see 
Figure 4-2. Your program can test any of the bits in this 
field using the mask given in the last column of Figure 
4-2. Your program may test more than one bit by the 
hexadecimal sum of the test values. 

All bits are set to when your program is assembled 
unless the X'nnnn' operand is sepcified. If this operand is 
specified, it is assembled into these two bytes. When your 
program is being executed, each bit may be set to 1 by 
your program (to request certain functions or specific 
feedback information) or by physical IOCS (as a result of 
having detected a particular condition). Any bits that can 
be turned on by physical IOCS during program execution 
are reset to zero by PIOCS the next time an EXCP macro 
is executed against the same CCB. 

Byte 4 is set to X'OO' whenever an EXCP macro is issued 
against the CCB. For non-teleprocessing devices, a 
program-controlled interruption (PCI) is ignored. 

The meaning of the bits in these two bytes is as follows: 



Byte 4: 

= attention 

1 = status modifier 
o ^^ '^on*rol ''nit end 

3 = busy 

4 = channel end 

5 = device end 

6 = unit check 

7 = unit exception 



Byte 5: 

= program-controlled 

interruption 

1 = incorrect length 

2 = program check 

3 = protection check 

4 = channel data check 

5 = channel control check 

6 = interface control check 

7 = chaining check 



4 Contents Of byte 6: 

X'Ou' = original CCB 

X'2u' = translated CCB 

X'4u' = BTAM-ES request against original CCB 

X'6u' = BTAM-ES request against translated CCB 

X'Su' = user-transiated CCB in virtual partition 

Note:. if u = 0: the address in byte 7 refers to a sys- 
tem logical unit. 

if u = 1 : the address in byte 7 referes to a pro- 
grammer logical unit 

Contents of byte 7: 

Hexadecimal representation of SYSnnn as follows: 



SYSOOO = 00 
SYS001 = 01 
SYS002 = 02 



SYS240=F0 



If bit 5 of CCB byte 2 is set to 1 and device end results as 
a separate interrupt, device end will be posted. 

Figure 4-1. Layout and contents of Command Control Block (CCB). 



SYSRDR = 00 
SYSIPT = 01 
SYSPCH = 02 
SYSLST = 03 
SYSLOG = 04 
SYSLNK = 05 
SYSRES = 06 
SYSSLB = 07 
SYSRLB = 08 
SYSUSE = 09 
SYSREC = OA 
SYSCLB = OB 
SYSVIS = OC 
SYSCAT = OD 

5 Address of CCW (or of the first of a chain of CCWs) asso- 

ciated with the CCB: 
This is a real address if CCB byte 6 = X'2u', X'6u', or 

X8u'. 
This is a virtual address if CCB byte 6 = X'Ou' or X'4u'. 

6 Either of the following: 

The CCW address contained in the CSW ai channel-end 
interrupt for the I/O operation involving the CCB; or 
the address of the associated channel appendage 
routine if CCB byte 1 2 contains X'40'. 

7 Bytes 1 6 to 23 are provided only if the sense operand 

was specified in the CCB macro. They accommodate 
the CCW for returning sense information to your 
program. 
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Condition Indicated 


On Values for 


Mask for Test 
Under Mask 


Byte 


Bit 






Third Ope- 






1(0N) 


(OFF) 


rand in CCB 
Macro 


Instruction 


2 


Traffic Bit (WAIT) 


I/O Completed. Normally 
set at Channel End. Set at 
Device End if bit 5 is on. 


I/O requested 
and not complet- 
ed. 




X'80' 


1 End of File on System Input 


/♦ or /& on SYSRDR or 






X'40' 






SYSIPT. Byte 4, Unit ex- 












ception Bit is also on. 










321 1 UCB Parity Check (line 


Yes 


No 








complete)^ 










2 Unrecoverable I/O Error 


I/O error passed back due 


No program or 




X'20' 






to program option or opera- 


operator option 










tor option. 


error was passed 
back. 






3' Accept Unrecoverable I/O Error 


Return to user after physi- 


Operator Option: 


X'1000' 


X'10' 




(Bit 2 is ON) 


cal IOCS attempts to cor- 
rect I/O error.^ 


Dependent on the 
Error 






4' Return: 


Operator Options: 


Operator Options: 


X'0800' 


X08' 




DASD data checks, 3540 data 


Ignore, Retry, or Cancel. 


Retry or Cancel. 








checks, 












2671 data checks, 1017/1018 


Ignore or Cancel. 


Cancel. 








data checks. 












5424/5425 not ready. 


Return to user. 










Indicate action type messages for 












DOC 










5' Post at Device End. Specify this 


Device End condition is 


Device End condi- 


X0400' 


X'04' 




bit to be set on for a 2560 or 


posted: that is, byte 2, bit 


tions are not postr 








5424/5425. 


and byte 3, bits 2 and 6 set 
at Device End. Also byte 4, 
bit 5 is set. 


ed. Traffic bit is 
set at Channel 
End. 






6' Return: Uncorrectable tape read 


Return to user; after physi- 


Operator Option: 


X'0200' 


X02' 




data check (2400 series or 3420); 


cal IOCS attempts to cor- 


Ignore or Cancel 








1 01 8, 2560 data check, 2520 or 


rect 321 1 ^ tape, or DASD 


for tapes, paper 








2540 punch equipment check; 


error; when 1 01 8 or 2560 


tape punch 








2560, 5424/5425 read, punch, 


data check"*; when 2560 or 


(1 01 8), card 








print data, and print clutch equip- 


5424/5425 equipment 


punches other 








ment checks; 3881 equipment 


check; when 3504, 3505, 


than 2560 and 








check; 3504, 3505, or 3525 per- 


3525 permanent error (byte 


5424/5425. Re- 








manent errors; DASD read or read 


3, bit 3 is also on)."*'^ 


try or Cancel for 








verify data check; 321 1 passback 




DASD, 2560, or 








requested; 3895 error codes re- 




5424/5425. 








quested. (Data checks on count 












not retained)^ 










7' User Error Routine 


User handles error 


A physical IOCS 


X'0100 


xor 






recovery.^ 


error routine is 
used unless the 
CCB sense ad- 
dress operand is 
specified. The 
latter requires 
user error re- 
covery. 







Figure 4-2. Conditions indicated by CCB bytes 2 and 3 (Part 1 of 3). 
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Byte 


Bit 


Condition Indicated 


On Values for 
Third Ope- 
rand in COB 
Macro 


Mask for Test 
Under Mask 
Instruction 


1 (ON) 


(OFF) 


3 


Data check in DASD count field. 
Permanent error for 3330, 3340, 
or 3350. 


Yes-Byte 3, bit 3 is off; 
Byte 2, bit 2 is on. 


No 




X'80' 




Data check - 1 287 or 1 288. 


Yes 


No 








MICR - SCU not operational. 


Yes 


No 








321 1 Print Check 's'''>i'^r»^<>"* 


1 oo 


No 








check).'-^ 












3540 special record transferred. 


Yes 


No 






1 DASD Track overrun. 


Yes 


No 




X'40' 




1 01 7 broken tape. 


Yes 


No 








Keyboard correction 1 287 in Jour- 


Yes 


No 








nal Tape Mode 












321 1 print quality error 


Yes 


No 








(equipment check)^. 












MICR intervention required. 


Yes 


No 






2 End of DASD Cylinder. 


Yes 


No 




X20' 




Hopper Empty 1 287/1 288 Docu- 


Yes 


No 








ment Mode. 












MICR- 

1 255/1 259/1 270/1 275/1 419, 


Document feeding stopped. 


No 








disengage. 












1 275/1 41 9D, I/O error in exter- 


Channel data check or Bus- 










nal interrupt routine. 


out check. 










321 1 /2245 line position error.^'^ 


Yes 


No 






3 Tape read data check (2400 se- 


Operation was unsuccess- 


No 




X'10' 




ries); 2520, 2540 or 3881 equip- 


ful. Byte 2, bit 2 is also on. 










ment check; any DASD data 


Byte 3, bit is off. 










check. 












1017, 101 8 data check. 


Yes 


No 








1 287, 1 288 equipment check. 


Yes 


No 








2560, 3203, 5203, 5424/5425 


Byte 2, bit 6 is also on. 


No 








read, punch, print data, and print 












clutch equipment checks. 












3504, 3505, 3525 permanent er- 


Byte 2, bit 6 is also on. 


No 








rors. 












321 1 data check/print check.** 


Yes 


No 








3540 data check. 


Yes 


No 






4 Nonrecovery Questionable Condi- 


Card: unusual command 






X'08' 




tion. 


sequence. For DASD, no 
record found. 1287, 1288 
document jam or torn tape. 
321 1 UCB parity check 
(command retry). 
5424/5425 not ready. 








5' No record found condition (retry 


Retry command if no record 


Set the nonrecov- 


X0004' 


X04' 




on 2311, 2314, 2319, 3330, 


found condition occurs 


ery questionable 








3340, or 3350). 


(disk). 


condition bit on 
and return to 
user. 







Figure 4-2. Conditions indicated by CCB bytes 2 and 3 (Part 2 of 3). 
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Byte 


Bit 


Condition Indicated 


On Values for 
Third Ope- 
rand in COB 
Macro 


Mask for Test 
Under Mask 
Instruction 


1(0N) 


(OFF) 


3 


6 Verify error for DASD or Carriage 
Cliannel 9 overflow. 

1 287 document mode: late stack- 
er select. 

1 288 End-of-Page (EOP). 


Yes. (Set on when Channel 
9 is reached only if Byte 2, 
bit 5 is on). 
Yes 

Yes 


No 

No 
No 




X'02' 


7' Command Chain Retry. Specify 
this bit to be set on if command 
chaining is used for a 2560 or 
5424/5425. 


Retry begins at last CCW 
executed.^ 


Retry begins at 
first CCW or 
channel program. 


X0001 • 


X'or 



Notes: 



1 User Option Bits. Set in CCB macro. Physical IOCS sets the other bits off at EXCP time and on when the specified condition 
occurs. 

2 I/O program check, command reject, or tape equipment check always terminates the program. 

3 You may not handle Channel Control Checks and Interface Control Checks. The occurence of a channel data check, unit check, or 
channel chaining check cause byte 2, bit X'20' of the CCB to turn on, and completion of posting and dequeuing to occur. I/O 
program and protection checks always cause program termination. Incorrect length and unit exception are treated as normal 
conditions (posted with completion). Also, you must request device end posting (CCB byte 2, bit X'04') in order to obtain errors 
after channel end. 

4 Error correction feature for 1018 is not supported by physical IOCS. When a 1018 data check occurs and CCB byte 2, bit X'02' is on, 
control returns directly to you with CCB byte 3, bit X'lO' turned on. 

5 A line position error on the 321 1 can occur as a result of an equipment check, data check, or FCB parity check. 

6 If an error occurs, physical IOCS updates the CCW address in bytes 9 through 1 1 of the CCB that is used for the pertinent I/O 
operation and is queued to the channel queue. 

7 A deleted or bad spot record has been read on a 3540 diskette. CCW chain broken, after CCW reads special record. 

8 321 1 remarks apply also to 32 1 1-compatible printers (that is, with device type code of PRTl). 3895 error codes are returned in CCB 
byte 8. Refer to the 3895 Document Reader/Inscriber manuals for information on these error codes. 



Figure 4-2. Conditions indicated by CCB bytes 2 and 3 (Part 3 of 3). 



CHECK Macro 



Name Operation Operand 



[name] CHECK 



(fdenamel(l)} 
[,control-address|,(0)] 



The CHECK macro prevents processing until data 
transfer on an I/O operation is complete. It must be 
issued either after a read or write macro is issued 
to a work file, or after a read is issued to a micr 
file. 

Because of differences in the way that IOCS posts 
CCB transmission information bits in the DTFs, you 
should always issue a CHECK macro to ensure that 
data transfer is complete before testing these bits. If 
the data transfer is completed without an error or 
other exceptional condition, CHECK returns control 
to the next sequential instruction. If an error condi- 
tion is encountered, control is transferred to the 
ERROPT address. If ERROPT is not specified, process- 
ing continues at the next instruction. If end-of-file is 
encountered, control transfers to the EOFADDR ad- 
dress. 

filename|(l): The operand specifies the name of 



the file associated with the record to be checked or, 
if register notation is used, the register containing a 
pointer to the field that contains this name. This 
name is the same as that specified for the DTFXX 
header entry for the file. 

Issuing a check macro after a read on a MiCR 
device allows you to query the micr document buff- 
er (see Figure 4-3) and to specify the control-address 
operand: 

control-address|(0): indicates the address to 
which control passes when a buffer is waiting for 
data or when the file is closed. If register notation is 
used, the specified register must point to a field that 
contains this address. 

The CHECK macro determines whether the MiCR 
document buffer contains data ready for processing, 
is waiting for data, contains a special nondata status, 
or the file (filename) is closed. If the buffer has data 
ready for processing, control passes to the next se- 
quential instruction. If the buffer is waiting for data, 
or the file is closed, control passes to the address 
specified for control address, if present. If the buffer 
contains a special nondata status, control passes to 
the ERROPT routine for you to examine the posted 
error conditions before determining your action. 
(See byte 0, bits 2, 3, and 4, of the document buffer). 
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Return from the ERROPT routine to the next sequen- 
tial instruction via a branch on register 14, or to the 
control address in register 0. 

If the buffer is waiting for data, or if the file is 
closed, and the control address is not present, con- 
trol is given to you at your erropt address specified 
in the dtfmr macro. 



If an error, a closed file, or a waiting condition 
occurs (with no control-address specified) and no 
ERROPT address is present, control is given to you at 
the next sequential instruction. 

If the waiting condition occurred, byte 0, bit 5 of 
the buffer is set to 1 . If the file was closed, byte 0, 
bits 5 and 6 of the buffer are set to 1 . 



MICR Document Buffer 



Buffer Status Indicators I 


Byte 


Bit 


Comment 






1 

2 

3 

4 

, 5 

6 

7 


The document is ready for processing (you need never test this bit). 

Unrecoverable stacker select error, but all document data is present. You may continue to issue 

GETs and READs. 

Unrecoverable I/O error. An operator I/O error message is issued. The file is inoperative and must 

be closed. 

Unit Exception. You requested disengage and all follow-up documents are processed. The LITE 
macro may be issued, and the next GET or READ engages the device for continued reading. 
Intervention required or disengage failure. This buffer contains no data. The next GET or READ 
continues normal processing. This indicator allows your program to give the operator information 
necessary to select pockets for documents not properly selected and to determine unread docu- 
ments. 

The program issued a READ, no document is ready for processing, byte 0, bits to 2 are off, or the 
file is closed (byte 0, bit 6 is on). The CHECK macro interrogates this bit. 

Note: You must test bits 1 through 4 and take appropriate action. Any data from a buffer should not 
be processed if bits 2, 3, or 4 are on. 

The program has issued a GET or READ and the file is closed. Bit 5 is also on. 
Reserved. 


1 



1-7 


Your stacker selection routine turns this bit on to indicate that batch numbering update (1419 only) 
is to be performed in conjunction with the stacker selection for this document. The document is 
imprinted with the updated batch number unless a late stacker selection occurs (byte 3, bit 2). 
Reserved. 

Note: If bits 6 or 7 (byte 2) are on, bit is ignored by the external interrupt routine. With the 1419 
(dual address) only, batch numbering update cannot be performed with the stacker selection of 
auto-selected documents. 


2* 




1-3 
4 
5 

6-7 


For 1 41 9 or 1 275 (dual address) only. An auto-select condition occurred after the termination of a 
READ but before a stacker select command. The document is auto-selected into the reject pocket. 
Reserved. 

Data check occured while reading. You should interrogate byte 3 to determine the error fields. 
Overrun occurred while reading. Byte 3 should be interrogated to determine the error fields. 
Overruns cause short length data fields. When the 1419 or 1275 is enabled for fixed-length data 
fields, bit 4 is set. 

The specific meanings of bits 6 and 7 depend on the device type, the model, and the Engineering 
Change level of the MICR reader; but if either bit is on, the document(s) concerned is (are) auto- 
selected into the reject pocket. 

1 . 1412 or 1270: Bit 6 on indicates that a late read condition occurred. Bit 7 on indicates 
that a document spacing error occurred. (Unique to the 1 270: both the current document and 
the previous document are auto-selected into the reject pocket when this bit is on. This 
previous document reject cannot be detected by IOCS, and byte 5 of its document buffer does 
not reflect that the reject pocket was selected). 

2. 1275 and 1419 (single address) without engineering change #125358: Bit 6 indicates 
that either a late read condition or a document spacing error occurred. Bit 7 indicates a 
document spacing error for the current document. 

3. 1255, 1259, 1275, and 1419 (single or dual address) with engineering change 
#125358: Bit 6 indicates that an auto-select condition occurred while reading a document. The 
bit is set at the termination of the READ command before the stacker select routine receives 
control, Bit 7 is always zero. 



Figure 4-3. MICR document buffer format (Part i of 2) 
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Buffer Status Indicator (Continued) 



Byte 



Bit 



Comment 



3* 



Field 6 valid.** 

Field 7 valid.** 

A late stacl<er selection (unit check late stacker select on the stacker select command). The 
document is auto-selected into the reject pocket. 

Amount field valid (or field 1 valid).* * 

Process control field valid (or field 2 valid). * * 

Account number field valid (or field 3 valid).* * 

Transit field valid (or field 4 valid). * * 

Serial number field valid (or field 5 valid). * * 

Notes: 

1 . For the 1 270, bits 3-7 are set to zero when the fields are read without error. 

2. For the 1 255, 1 259, 1 275, and 1 41 9, bits 3-7 are set on when each respective field, including 
bracket symbols, is read without error. This applies to bits 0, 1 , and 3-7 on the 1 259 and 1 41 9 
model 32. 

3. For the 1 255, 1 259, 1 275, and 141 9, unread fields contain zero bits. Errors are indicated 
when an overrun or data check condition occurs while reading the data field. 



Byte 2 (bits 4, 5, 6, and 7) and byte 3 contain MICR sense information. 

Only for the 1 259 model 34 or 1419 model 32. Bits and 1 are not used for other models. 



Inserted pocket code determination by your stacker select routine. Whenever byte 0, bits 2, 3, or 4 
are on, this byte is X'OO' because no document was read and your stacker selection routine was not 
entered. Whenever auto-selection occurs, this value is ignored. A no-op (X'03') is issued to the 
device, and a reject pocket value (X'CF') is placed in byte 5. The pocket codes are (byte 2, bit 6 or 
7 on): 

Pocket A- X'AF'* 
Pocket B-X'BF'** 
Pocket - X'OF' 
Pocket 1 -X'lF' 
Pocket 2 - X'2F' 
Pocket 3 - X'3F' 
Pocket 4 - X'4F" 



Pocket 5 - X'5F' 




Pocket 6 - X'6F' 


Except 1 270 


Pocket 7 - X'7F' 


models 1 and 3 


Pocket 8 - X'8F' 




Pocket 9 - X'9F' 




Reject 




Pocket - X'CF' 





The actual pocket selected for the document. The contents are normally the same as that in byte 4. 



Note: 



X'CF' is inserted whenever auto-selection occurs (byte 2, bit 6; byte 2, bit 7; byte 2, bit 0; or 
byte 3, bit 2). These conditions may result from late READ commands, errant document 
spacing, or late stacker selection. 

a. Start I/O for stacker selection is unsuccessful (byte 0, bit 1). 

b. An 1/0 error occurs (for example, invalid pocket code) on the 1419 (dual address) 
secondary control unit when selecting this document. 



Additional User Work Areas 



This additional buffer area can be used as a work area and /or output area. Its size is determined by the DTFMR ADDAREA 
operand. The only size restriction is that this area, plus the 6-byte status indicators and data portion must not exceed 256 
bytes. This area may be omitted. 



Document Data Area 



The document data area immediately follows your work area. The data is right-adjusted in the document data area. The length 
of this data area is determined by the DTFMR RECSIZE operand. 



1 275, 1 41 9, and 1 270 models 2 and 4 only. 
1275 and 1419 only. 



Figure 4-3. MICR document buffer format (Part 2 of 2) 
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CLOSE and CLOSER Macros 

The CLOSE or closer macro is used to deactivate 
previously opened files; they end the association 
between a logical file declared in a program and a 
specific physical file on an I/O device. 

A file may generally be closed at any time, with 
the following exceptions; 

• Console files need not be closed; the CLOSE(R.) 
macro is invalid for files defined by means of 
the DTFCN. 

• Files assigned to an fba device may not be 
closed in an ERROPT routine. 

Files (such as on an fba device) that use control 
interval format must be closed in order to ensure 
that data in the control interval buffer be physically 
written on the fba device. 

No further commands can be issued to the closed 
file until it is reopened. 

The format of the close macro is 

Name Operation Operand 



[name] 



{CLOSEI 
CLOSER} 



(filenamelKrl)} 
[,filename2|(r2)]... 



The format of the closer macro is the same except 
that you code CLOSER instead of CLOSE in the opera- 
tion field. 

When CLOSER is specified, the symbolic address 
constants that CLOSER generates from the parameter 
list are self-relocating. When CLOSE is specified, the 
symboUc address constants are not self-relocating. 

To write the most efficient code in a multipro- 
gramming environment it is recommended that 
CLOSER be used. 

Enter the symbolic name of the file (assigned in 
the DTF header entry) in the operand field. A maxi- 
mum of 16 files may be closed by one macro by en- 
tering additional filename parameters as operands. 
Alternatively, you can load the address of the file- 
name in a register and specify the register using or- 
dinary register notation. The high-order 8 bits of 
this register must be zeros. For closer, the address 
of filename may be preloaded into any of the regis- 
ters 2 through 15. For close, the address of filen- 
ame may be preloaded into register or any of the 
registers 2 through 15. 

Notes: 

1. If you use register notation, we recommend that you follow 



the practice of using only registers 2 through 12. 

2. If CLOSE or CLOSER is issued to an unopened tape input 
file, the option specified in the DTF rewind option is per- 
formed. If CLOSE or CLOSER is issued to an unopened 
tape output file, no tapemark or labels are written. 

CNTRL Macro 

Name Operation Operand 



[name] CNTRL 



{filename|(l)} ,code[,nl][,n2] 



The CNTRL (control) macro provides commands for 
magnetic tape units, card devices, printers, dasds, 
and optical readers. (Note that if the device is an 
FBA DASD, the CNTRL macro is treated as a no-op or 
null operation.) Commands apply to physical non- 
data operations of a unit and are specific to the unit 
involved. They specify such functions as rewinding 
tape, card stacker selection, and line spacing on a 
printer. For optical readers, commands specify 
marking error lines, correcting a line for journal 
tapes, document stacker selecting, or ejecting and 
incrementing documents. The CNTRL macro does 
not wait for completion of the command before re- 
turning control to you, except when certain mne- 
monic codes are specified for optical readers. 

CNTRL usually requires two or three parameters. 
The first parameter must be the name of the file 
specified in the DTF header entry. It can be specified 
as a symbol or in register notation. 

The second parameter is the mnemonic code for 
the command to be performed. This must be one of 
a set of predetermined codes (see Figure 4-4). 

The third parameter, nl, is required whenever a 
number is needed for stacker selection, immediate 
jmntetjcamagejiQiitiQlj or for line or pagelnafEng 
on the 3886. The fourth parameter, n2, applies to 
delayed spacing or skipping or to timing mark check 
on the 3886. In the case of a printer file, the parame- 
ters nl and n2 may be required. 

The CNTRL macro must not be used for printer or 
punch files if the data records contain control char- 
acters and the entry CTLCHR is included in the file 
definition. 

Whenever CNTRL is issued in your program, the 
DTF CONTROL Operand must be included (except for 
DTFMT and DTFDR) and CTLCHR must be omitted. 
If control characters are used when CONTROL is 
specified, the control characters are ignored and 
treated as data. 
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IBM Unit 


Mnemonic Code 


"l 


"2 


Command 


2400, 3410, 3420 Series Magnetic Tape Units 


REW 






Rewind Tape 


RUN 






Rewind and Unload Tape 


ERG 






Erase Gap (Writes Blank Tape) 


WTM 






Write Tapemark 


BSR 






Backspace to Interrecord Gap 


BSF 






Backspace to Tapemark 


BSL 






Backspace Logical Record 


FSR 






Forward Space to Interrecord Gap 


FSF 






Forward Space to Tapemark 


FSL 






Forward Space Logical Record 


1442, 2520 Card Read Punch 


SS 


1 
2 




Select Stacker 1 or 2 


E 






Eject to Stacker 1 (1442 only) 


2540 Card Read Punch 
3504, 3505 Card Readers 
3525 Card Punch 


PS 


1 
2 
3 




Select Stacker 1, 2, or 3 (For 3504, 3505, and 3525, 3 Defaults 
to Stacker 2) 


2560 Multi -Function Card Machine 


SS 


1 
2 
3 
4 
5 




Select Stacker 1, 2, 3, 4, or 5 


2596 Card Read Punch 


SS 


1 
2 




Select Stacker 1 for Read, or Stacker 3 for Punch 
Select Stacker 2 for Read, or Stacker 4 for Punch 


5424/5425 Multi -Function Card Unit 


SS 


1 
2 
3 
4 




Select Stacker 1 , 2, 3, or 4 


1403, 1443, 3203, PRT1, 3800, 5203 Printers 
3525 Card Punch with Print Feature 1 


SP 


See 
c 


viote 
d 


Carriage Space 1, 2, or 3 lines 


SK 


c 


d 


Skip to Channel c and/or d (For 3525, a Skip to Channel 1 is 
Valid Only for Print Only Files) 


1403, 5203 Printers with Universal Character 
Set Feature or 3203, PRT1 , or 3800 Printers 1 


UCS 


ON 
OFF 




Data Checks are Processed with an Operator Indication 
Date Checks are ignored and Blanks are Printed 


PRT1 Printer 1 


FOLD 






Print Upper Case Characters for any Byte with Equivalent Bits 2-7 


UNFOLD 






Print Character Equivalents of any EBCDIC Byte 


231 1 , 2314, 2319, 3330, 3333, 3340, 3344 
DASD2 


SEEK 






Seek to Address 


3881 Optical Mark Reader 


PS 


1 
2 




Select Stacker 1 or 2 


1 287 Optical Reader 


MARK 






Mark Error Line in Tape Mode 


READKB 






Read 1287 Keyboard in Tape Mode 


EJD 






Eject Document 


SSD 


1 
2 
3 
4 




Select Stacker A, B, Reject, or Alternate Stacking Mode 


ESD 


1-4 




Eject Document and Select Stacker 


INC 






Increment Document at Read Station 


1 288 Optical Page Reader 


ESD 


1 
3 




Select Stacker A 
Reject Stacker (R) 


INC 






Increment Document at Read Station 


3886 Optical Character Reader 


DMK 


name (r) 
number 




Page mark the document when it is stacker selected as specified in 
parameter n^. 


LMK 


name (r) 
number, 
number 




Line mark the document when it is stacker selected as specified in 
parameter n^. 


ESP 


1 
2 


name (r) 
number 


Eject and stacker select the current document to stacker A or B. 
Perform line mark station timing mark check as indicated in 
parameter n2. 



c = An Integer that Indicates Immediate Printer Control (before printing), 
d = An Integer that Indicates a Delayed Printer Control. 

1 Note: PRT1 refers to 321 1 -compatible printers (that is, with a device type of PRT1 ). 

2 Note: This includes the 3350 operating in 3330 compatibility mode. 



Figure 4-4. CNTRL macro command codes 
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DI SEN Macro 



Name Operation Operand 



[name] DISEN 



{filenamel(l)} 



ENDFL Macro 



Name Operation Operand 



[name] ENDFL 



{filenamel(O)} 



This macro stops the feeding of documents through 
the magnetic character reader or optical 
reader/sorter. The program proceeds to the next 
sequential instruction without waiting for the disen- 
gagement to complete. You should continue to issue 
GETS or READS until the unit exception bit (byte 0, 
bit 3), of the buffer status indicators is set on (see 
Figure 4-3). 

The only required operand specifies the name of 
the file to be disengaged. This name is the same as 
that specified for the dtfmr header entry for the 
file. The operand can be specified either as a symbol 
or in register notation. 

DSPLY Macro 

Name Operation Operand 



[name] DSPLY 



{filename|(l)},(r2),{r3) 



The DSPLY macro displays the document field on 
the 1287 display scope! A complete field may be 
keyboard-entered if a 1287 read error makes this 
type of correction necessary. An unreadable charac- 
ter may be replaced by the reject character either by 
the operator (if processing in the on-line correction 
mode) or by the device (if processing in the off-line 
correction mode). You may then use the DSPLY 
macro to display the field in error. 

DSPLY always requires three parameters. The t~irst 
parameter is the symbolic name specified in the 
DTFOR header entry for the 1287 file. The second 
parameter specifies a general-purpose register (any 
from 2 to 12) into which the problem program 
places the address of the load format ccw giving the 
document coordinates for the field to be displayed. 
When the dsply macro is used in the corexit rou- 
tine, the address of the load format ccw can be ob- 
tained by subtracting 8 from the 3 -byte address that 
is right-justified in the full word location beginning 
at filename+32. (The high-order fourth byte of this 
full word should be ignored.) If the DSPLY macro is 
not used in the corexit routine, you must deter- 
mine the load format CCW address. The third par- 
ameter specifies a general-purpose register (2 
through 12) into which you place the address of the 
load format ccw giving the coordinates of the refer- 
ence mark associated with the displayed field. 



The ENDFL (end file load mode) macro ends the 
mode initiated by the SETFL macro. The name of 
the file to be loaded is the only parameter required, 
and is the same as the name specified in the DTFIS 
header entry for the file. The filename can be speci- 
fied either as a symbol or in register notation. Regis- 
ter notation is necessary if your program is to be 
self-relocating. The ENDFL macro must be issued 
only after a setfl and before a close or closer. 

The ENDFL macro performs an operation similar 
to CLOSE or CLOSER for a blocked file. It writes the 
last block of data records, if necessary, and then 
writes an end-of-file record after the last data re- 
cord. Also, it writes any index entries that are need- 
ed followed by dummy index entries for the unused 
portion of the prime data extent. 

BRET Macro 

Name Operation Operand 



[name] ERET 



{SKIP|IGN0RE|RETRY} 



This macro enables your program's ERROPT or 
WLRERR routine to return to iocs and specify an 
action to be taken. The macro applies only to dtfis, 
DTFMT, DTFSD and DTFDU files with the errext 
operand specified. 

The skip operand passes control back to the logic 
module to skip the block of records or control inter- 
val in error and process the next one. For disk or 
diskette output, an eret skip is treated as an eret 

IGNORE. 

The IGNORE operand passes control back to the 
module to ignore the error and continue processing. 

The RETRY operand causes the module to retry 
the operation that resulted in the error. With 
MTMOD for any error or with SDMOD wrong-length 
record errors, retry cancels the job with an invalid 
SVC message. 



ESETL Macro 



Name Operation Operand 



[name] ESETL 



{filename 1(1)} 



The ESETL (end set limit) macro ends the sequential 
mode initiated by the setl macro. For filename 
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specify the same name as was specified in the DTFis 
header entry. The name can be specified as a sym- 
bol or in register notation. If the records are 
blocked, ESETL writes the last block back if a PUT 
was issued. Register notation is necessary if your 
program is to be self-relocating. 

Note: If ADDRTR and/or RANSEQ are specified in the same 
DTP, ESETL should be issued before issuing a READ or 
WRITE; another SETL can be issued to restart sequential retriev- 
al. Sequential processing must always be terminated by issuing 
an ESETL macro. 

EX CP Macro 

Name Operation Operand 



[name] EXCP 



(blockname|(l)} 
[,REAL] 



The EXCP (execute channel program) macro re- 
quests physical IOCS to start an input/output opera- 
tion for a particular i/o device. 

Physical IOCS determines the device from the CCB 
or lORB control block specified by blockname. Phys- 
ical IOCS places the block in a queue of such blocks 
and returns control to the problem program. Physi- 
cal IOCS causes the channel program to be executed 
as soon as the channel and device are available. I/O 
interruptions are used to process i/o completion and 
to start I/O for requests if the channel or device was 
busy at the time the EXCP was executed. 

blockname: is the virtual address of the control 
block estabhshed for the device. It can be given as a 
symbol or in register notation. 

REAL: indicates that the addresses in the ccws 
and the address in the control block pointing to the 
first ccw have already been translated into real ad- 
dresses; the operand causes the DOS/VSE ccw trans- 
lation routine to be skipped. (For a program run- 
ning in real mode, the operand is ignored.) 

In your program, the EXCP macro with the real 
operand must be preceded by the PFIX macro that 
causes dos/vse (1) to page in those program pages 
which contain the pertinent control block, channel 
program, I/O areas, and IDA (indirect address) words 
(if used) and (2) to fix these pages in their page 
frames. 

Notes: 

1 . If the I/O area being used crosses page boundaries, the data 
address in the appropriate CCW(s) must point to the 
required indirect data address words within your program; 
in addition, bit 37 (the IDA bit) of these CCWs must be set 
tol. 



2. A channel program has to start with: 

- a long seek command in the case of a CKD DASD. 

- a define extent command in the case of an FBA DASD. 

The data chaining and, in S/370 mode, also the IDA bit 
must be set to zero. 

FEOV Macro 

Name Operation Operand 



[name] FEOV 



{filename|(l)) 



The FEOV (force end-of-volume) macro is used for 
files on magnetic tape (programmer logical units 
only) to force an end-of-volume condition before 
sensing a reflective marker. This indicates that proc- 
essing of records on one volume is considered fin- 
ished, but that more records for the same logical file 
are to be read from, or written on, a following vol- 
ume. For system units, see "SEOV Macro". 

The name of the file is the only parameter re- 
quired. The name can be specified either as a sym- 
bol or in register notation. 

When physical iocs macros are used and dtfph 
is specified for standard label processing, FEOV may 
be issued for output files only. In this case, FEOV 
writes a tapemark, the standard trailer label, and 
any user-standard trailer labels if DTFPH labaddr 
is specified. When the new volume is mounted and 
ready for writing, IOCS writes the standard header 
label and user-standard labels, if any. 

FEOVD Macro 

Name Operation Operand 



[name] FEOVD 



{filename|(l)} 



The FEOVD (force end-of-volume for disk) macro is 
used for either input or output files to force an end- 
of-volume condition before it actually occurs. This 
indicates that processing of records on one volume is 
finished, but that more records for the same logical 
file are to be read from, or written on, the following 
volume. If extents are not available on the new vol- 
ume, or if the format- 1 label is posted as the last 
volume of the file, control is passed to the EOF ad- 
dress specified in the DTF. 

The name of the file is the only required operand. 
The name can be specified either symbolically or in 
register notation. 
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GENIORB Macro 



Name Operation Operand 



[name] GENIORB [ADDRESS=(namel|(S,namel)|(l)}] 
[,LENGTH=fieldlength] 
,CCW= {name2|(S,name2)|(r2)) 
,{DEVICE=SYSxxx| 
LOGUNIT={name3|(S,name3)| (r3)}} 
[,FIXLIST= (name4|(S,name4)| fr4)} ] 
[,FIXFLAG=(optionll,...)] 
[,IOFLAG=(option21,...)] 
[,ERREXIT= (name5|(S,name5)j (r5)}] 
[,ECB= (name6|(S,name6)|(r6)} ] 



length of the lORB will be used; however, the assem- 
bler issues an MNOTE. If the ADDRESS operand is 
omitted, LENGTH will not be used. 

CCW= {name2|(S,name2)|(r2)} : This operand 
gives the name of the first CCW used with the lORB. 
The name must be the same as the name specified in 
the assembler ccw statement that builds the ccw. 

DEVICE=SYSxxx: This operand specifies the 
symbolic unit for the actual I/O unit with which the 
lORB is associated. 



The GENIORB macro generates an lORB 
(Input/Output Request Block). The block is gener- 
ated at the time of program execution. For the lay- 
out and contents of an lORB, see Figure 4-5. The 
lORB is an alternative to the CCB; instead of speci- 
fying a CCB in the EXCP macro, the address of an 
lORB is given. If used in a program that is to be exe- 
cuted under DOS/VSE operating in ECPS:VSE mode, 
the lORB allows for the specification of areas to be 
page-fixed for the I/O operation. Such areas include 
the lORB and the channel programs themselves and 
all input/output areas. Specifying those areas frees 
the DOS/VSE page-fixing routines from having to 
scan the channel programs to determine which areas 
are to be fixed. 

The GENIORB does not provide for SENSE ccws. 
GENIORB and CCB may be used interchangeably, 
depending on the required functions. 

In s/370 mode, the GENIORB macro is accepted, 
but a fixlist, if specified, is not used. 

After execution of the macro, 

register 1 contains the address of the lORB, and 
register 1 5 contains the return code from an 
implicit GET VIS. 

For a detailed display in your assembly, showing 
the lORB fields and their meaning, issue the lORB 
macro, with the (only) operand DSECT=YES. 

ADDRESS= {namel|(S,namel)|(l)}: If speci- 
fied, this operand gives the name of the area in 
which the lORB is to be generated. The address 
operand can be specified only together with the 
length operand. 

Omitting the ADDRESS operand indicates that the 
required area is to be obtained thru an implicit 
GETVis issued by dos/vse. 



LOGUNIT={name3|(S,name3)|(r3)): This ope- 
rand describes the device in logical unit format. It 
points to a halfword with the same format as a logi- 
cal unit number (bytes 6 and 7 ) in a CCB; see Figure 
4- 1 provided in context with the discussion of the 
CCB macro. 

For a description of the fixlist, fixflag, and 
lOFLAG operands, refer to the lORB macro. 

ERREXIT={name5|(S,name5)|(r5)}: ERREXIT is 
the address of a routine to be executed should 
dos/vse be unable to obtain the required virtual 
storage. If the ERREXiT operand is omitted, failure 
to obtain virtual storage causes dos/vse to cancel 
the program (task). 

ECB= {nanie6|(S,name6)|(r6)} : This operand 
specifies the address of the ECB to be posted when 
I/O is complete. For a more detailed description of 
the ECB operand, refer to the lORB macro. 

GET Macro 

Name Operation Operand 



[name] GET 



(filename|(l)) 
[,workname|,(0)] 



gIet makes the next sequential logical record from 
an input file available for processing in either an 
input area or in a specified work area. It is used for 
any input file in the system, and for any type of re- 
cord: blocked or unblocked, fixed or variable 
length, and undefined. 

If GET is used with a file containing checkpoint 
records, the checkpoint records are bypassed auto- 
matically. 



LENGTH=field length: This operand gives the 
length of the field provided for IORB generation. 
The value must be given as a selfdefming term. If 
this operand is omitted a default value equal to the 



filename: This operand is required. The parame- 
ter value must be the same as specified in the header 
entry of the DTF macro for the file from which the 
record is to be retrieved. The filename can be speci- 
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fied as a symbol or in either special or ordinary reg- 
ister notation. The latter is necessary to make your 
programs self-relocating. 

workname: This is an optional parameter speci- 
fying the work area name or a register (in either 
special or ordinary register notation) containing the 
address of the work area. The work area address 
should never be preloaded into register 1 . This par- 
ameter is used if records are to be processed in a 
work area which you define yourself (for example, 
using a DS instruction). If the operand is specified, 
all GETS for the named file must use a register or a 
workname. Using the second operand causes get to 
move each individual record from the input area to 
a work area. The workname parameter is not valid 
for the 3881. You also cannot specify the WORK A 
operand in the dtfcd for the 3 8 8 1 . 

In conjunction with optical reader input, this 
macro can be used only to retrieve records from a 
journal tape on a 1287. 

lORB Macro 

Name Operation Operand 

[name] lORB DSECT=YES 

or 

CCW=namel|,DEVICE =SYSxxx, 
[,FIXLIST=name2] 
[,FIXFLAG=(optionl 1,...)] 
[,IOFLAG=(option21,...)] 
[,ECB=name3] 



CCW=namel: This operand give the name of the 
first ccw used with the iorb. This name must be 
the same as the name specified in the assembler ccw 
statement that builds the ccw. 

DEVICE=SYSxxx: This operand specifies the 
symbolic unit for the actual I/O unit with which this 
IORB is associated. 

FIXLIST=name2: This operand specifies the 
address of the first of two or more fixlist parts or of 
the only fixlist part. In ecps-.vse mode, the fixlist 
operand is required unless fixflag=fixed is speci- 
fied. Each fixlist part consists of one or more 8-byte 
entries plus an end or chaining indicator as shown in 
Figure 4-6. 



Bytes 



16 



24 



Residual 
count 



Transmission 
information 



CSW 
status bits 



reserved 



reserved 



CCW address 
from CSW 



reserved 



* Same as for a CCB (see Figure 4- 1 ) 

Figure 4-5. Layout and contents of the I/O Request Block 
(IORB) 



The IORB macro generates an IORB (Input/Output 
Request Block). The block is generated when your 
program is being assembled. For the layout and 
contents of an IORB, see Figure 4-5. 

The IORB is an alternative to the CCB: instead of 
specifying a CCB in the EXCP macro, the address of 
an IORB is given. If used in a program that is to be 
executed under dos/vse operating in ECPS:VSE 
mode, the IORB macro allows for the specification of 
areas to be page-fixed for the I/O operation. Such 
areas include the IORB and the channel programs 
themselves and all input/output areas. Specifying 
those areas frees the DOS/vSE page-fixing routines 
from having to scan the channel programs to deter- 
mine which areas are to be fixed. 

The IORB does not provide for SENSE ccws. IORB 
and CCB may be used interchangeably, depending 
on the required functions. 

In s/370-mode the IORB is accepted, but the speci- 
fied fixlist (see the discussion of operand 
FlXLlST=name2, below) is not used. 



X'OO' 
\ 


begin address 


X'OO' 


end address 



0\ \ 1 



L 



chaining indicator 



x'or 


address of next 
fixlist part 



D 

L 



end indicator T^X'OO' or X'01' 
Figure 4-6. Layout of fixlist 
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In a fixlist entry, begin address and end address 
are the addresses of the first and the last byte of an 
area which has to be fixed for the I/O request (begin 
address <, end address; entries with begin address > 
end address will be ignored). Each entry describes a 
storage area that is accessed by the channel during 
the I/O request; that is, an area containing the chan- 
nel program, an input/output area, or the lORB. 

Duplicate entries and entries describing overlap- 
ping storage areas are allowed. As a result, certain 
areas may be covered more than once by the fixlist. 
The system will compress the fixlist so that each 
page to be fixed for the channel program is covered 



VXXXJr VXXW. 



However, speciiyuig 



FiXFLAG=(COMPRESSED) indicates that this service is 
not desired. 

FIXFLAG=(optionll, ...)*• This operand specifies a 
list of options which apply to the I/O fixing proce- 
dure. 

The options you can specify are: 

COMPRESSED to indicate that the system does not 
have to compress the fixlist. Use 
this option if the fixlist is already 
compressed, that is: each page to be 
fixed for the I/O request is covered 
only once by the fixUst. 

FIXED to indicate that all areas which 

should be fixed for the I/O opera- 
tion have already been fixed by the 
user, there is no fixlist. In s/370 
mode, this specification is ignored. 

IOFLAG=(option21,...): A list of options may be 
specified which apply to I/O interrupt handling: 

POSTDE to indicate that device end is to be post- 
ed. 

POSTERR to indicate that an unrecoverable I/O 
error is to be accepted. 

SKIPERP to indicate that error recovery by the 
system is to be skipped. 

ECB=name3: This operand specifies the address of 
the ECB to be posted when I/O is complete. The 
traffic bit (byte 2, bit 0) of the ECB must have been 
cleared before issuing the EXCP macro. The ECB 
operand must be specified if a fixlist is used. 

Note: If FIXFLAG=FIXED is specified, the ECB must have 
been PFIXed. 



Specifying DSECT=YES causes the assembler to 
display, as a DSECT structure, the lORB and the 
meaning of its fields. 

LBRET Macro 

Name Operation Operand 



al T t>D CT 
.^1 ijL»XV-l^i 



iM^p; 



The LBRET macro is issued in your subroutines 
when you have completed processing labels and 
wish to return control to IOCS. LBRET appUes to 
subroutines that write or check DASD or magnetic 
tape user-standard labels, write or check tape non- 
standard labels, or check dasd extents. The ope- 
rand used - 1, 2, or 3 - depends on the function to 
be performed. The functions and operands are ex- 
plained below. 

Checking User Standard DASD Labels: iocs 
passes the labels to you one at a time until the maxi- 
mum allowable number is read (and updated), or 
until you signify you want no more. In the label 
routine, use LBRET 3 if you want IOCS to update 
(rewrite) the label just read and pass you the next 
label. Use LBRET 2 if you simply want IOCS to read 
and pass the next label. If an end-of-file record is 
read when LBRET 2 or LBRET 3 is used, label check- 
ing is automatically ended. If you want to eliminate 
the checking of one or more remaining labels, use 

LBRET 1. 

Writing User Standard DASD Labels: Build 
the labels one at a time and use LBRET to return to 
IOCS, which writes the labels. Use LBRET 2 if you 
want control returned to you after iocs writes the 
label. If, however, IOCS determines that the maxi- 
mum number of labels has already been written, 
label processing is terminated. Use lbret 1 if you 
wish to stop writing labels before the maximum 
number of labels is written. 

Checking User Standard Tape Labels: iocs 
reads and passes the labels to you one at a time until 
a tapemark is read, or until you indicate that you do 
not want any more labels. Use lbret 2 if you want 
to process the next label. If iocs reads a tapemark, 
label processing is automatically terminated. Use 
lbret 1 if you want to bypass any remaining labels. 



DSECT=YES: If the operand is specified, it should Writing User Standard Tape Labels: Build the 



be the only one. Any other parameters specified in 
the macro are ignored and an appropriate MNOTE is 
generated by the assembler. 



labels one at a time and return to iocs, which writes 
the labels. When LBRET 2 is used, IOCS returns con- 
trol to you (at the address specified in labaddr) 
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after writing the label. Use lbret 1 to terminate the 
label set. 

Writing or Checking Nonstandard Tape Labels: 

You must process all your nonstandard labels at 
once. Use lbret 2 after all label processing is com- 
pleted and you want to return control to iocs. 

LITE Macro 

Name Operation Operand 



[name] LITE 



(filename 1(1)} 
[,light-switches|,(0)] 



This macro lights any combination of pocket lights 
on a 1419 magnetic character reader or 1275 optical 
reader/sorter. Before using the LITE macro, the 
DISEN macro must be issued to disengage the device. 
Processing of the documents should be continued 
until the unit exception bit (byte 0, bit 3) of the doc- 
ument buffer status indicators is set on (see Figure 
4-3). When this bit is on, the follow-up documents 
have been processed, the MICR reader has been di- 
sengaged, and the pocket LITE macro can be issued. 

The first operand is the name of the file; this 
name is the same as that specified for the dtfmr 
header entry for the file. The second operand indi- 
cates a 2-byte area containing the pocket Ught 
switches. Both operands can be given either as a 
symbol or in register notation. 

The bit configuration for the pocket light switch 
area is shown in Figure 4-7. The pocket lights that 
are turned on should have their indicator bits set to 
1. If an error occurs during the execution of the 
pocket lighting I/O commands, bit 7 in byte 1 is set 
to 1 . This error condition normally indicates that 
the pocket light operation was unsuccessful. 

NOTE Macro 

Name Operation Operand 
[name] NOTE {filename|(l)} 



The NOTE macro obtains identification for a physi- 
cal record or logical block that is read or written 
during processing. At least one read or write op- 
eration should be successfully completed by means 



of the CHECK macro before issuing the NOTE macro. 
To NOTE a desired record successfully, the pointr, 
points, or pointw macros must not be issued be- 
tween CHECK and NOTE. 

For magnetic tape, the last record read or written 
in the specified file is identified by the number of 
physical records read or written from the load point. 
The physical record number is returned in binary in 
the three low-order bytes of register 1. The high- 
order byte contains binary zero. 

For CKD DASD, the binary number returned in 
register 1 is in the form cchr, where 

cc = cylinder number, 

h = track number, 

r = record number within the track. 

Register contains the unused space remaining 
on the track following the end of the identified re- 
cord. 

/ " 

'^ For FBA devices, register 1 contains an address 

relative to the begining of the file in the form cccb, 
where ccc is the relative number of the current con- 
trol interval (origin 0), and b is the relative block 
number within the current Ci (origin 1). Register 
contains the length of the longest logical block that 
could completely fit in the CI following the NOTEd 
logical block. 

You must provide a four- or six-byte field and 
store in it the record identification and the remain- 
ing capacity so that it can be used later by a pointr 
or pointw macro to find the NOTEd record again. 
The two-byte track or CI capacity remaining is need- 
ed only when a write sq is to follow the pointr or 

POINTW. 

OPEN and OPENR Macros 

The OPEN or OPENR macro activates all files. 

When OPENR is specified, the symbolic address 
constants that openr generates from the parameter 
list are self-relocating. When open is specified, the 
symbolic address constants are not self-relocating. 
The format of the OPEN macro is 

Name Operation Operand 



[name] OPEN 



(filename 1 1 (rl)) 
[,filename2|,(r2)] ... 



Bits 





1 


2 


3 


4 


5 


6 


7 


8 


9 


A 


B 


C D E 


F 


Pocket Lights 


A 


B 





1 


2 


3 


4 


5 


6 


7 


8 


9 


Reserved 


Error indicator 
bit 



Figure 4-7. Bit configuration for pocket light switch area of the 1419 
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The format of the openr macro is the same except 
that you code openr instead of OPEN in the opera- 
tion field. 

Enter the symbolic name of the file (dtp file- 
name) to be opened in the operand field. A maxi- 
mum of 16 files may be opened with one OPEN or 
OPENR by entering the filenames as additional ope- 
ra nds= 

Self-relocating programs using LIOCS must use 
OPENR to activate all files, including console files. In 
addition to activating files for processing, OPENR 
relocates all address constants within the DTP tables 
(zero constants are relocated only when they consti- 
tute module address). 

To write the most efficient code in a multipro- 
gramming environment it is recommended that 
OPENR be used. 



Name Operation Operand 



[name] POINTS 



(filename 'i(l)} 



For a tape file, the tape is rewound. If the file con- 
tains any header labels, they are bypassed, and the 
tape is positioned to the first record following the 
label set. 

For disk, the file is repositioned to the lower limit 
of the first extent. A points should not be followed 
by a WRITE UPDATE. If a points is followed by a 
WRITE SQ, the first record in the file is overwritten. 
For CKD DASD, the remainder of the track is then 
erased (overwritten with zeros). For pba devices, the 
remainder of the CI is erased (overwritten with ze- 
ros) and an SEOP is written (the following ci is also 
overwritten with zeros). 



POINTR Macro 



POINTWMacro 



Name Operation Operand 



[name] POINTR 



(filename 1(1)} 
,(address|(0)} 



The POINTR macro repositions the file specified by 
filename to the record identified by previouly issu- 
ing a NOTE macro. The filename may be expressed 
either as a symbol or in register notation. 

addressi (0): specifies a virtual storage location in 
which is stored either a four-byte record identifier or 
a four-byte record identifier plus a two-byte track or 
CI capacity. The four- or six-byte number must be 
in the form obtained from the note macro. The 
two-byte track or CI capacity is required only when 
a WRITE SQ is to be issued following the POINTR. 

If a READ follows the POINTR, the NOTEd record 
is the record read. 

For magnetic tape, a WRITE must not follow a 

POINTR. 

For DASD, if a WRITE UPDATE foUows the 
POINTR, the NOTEd record is written (or overwrit- 
ten). If a WRITE SQ follows the POINTR, the record 
after the NOTEd record is written (or overwritten) 
and, on CKD DASD, the remainder of the track is 
erased (overwritten with zeros). On PBA devices, the 
remainder of the CI is erased (overwritten with ze- 
ros) and an SEOP is written (the following CI is also 
overwritten with zeros). 

POINTS Macro 

The POINTS macro repositions a file to its beginning. 



Name Operation Operand 



[name] POINTW 



(filename|(l)} 
, (addressi (0)} 



The POINTW macro repositions the file specified by 
filename to the record following the record identi- 
fied by previously issuing a NOTE macro. The file- 
name may be expressed either as a symbol or in 
register notation. 

addressi (0): specifies a virtual storage location in 
which is stored either a four-byte record identifier or 
a four-byte record identifier plus a two-byte track or 
CI capacity. The four- or six-byte number must be 
in the form obtained from the note macro. The 
two-byte track or CI capacity is required only when 
a WRITE SQ is to be issued following the pointw. 

If a READ follows the POINTW, the record after 
the NOTEd record is read. 

For DASD, if a write update follows the 
POINTW, the record after the NOTEd record is written 
(or overwritten). If a WRITE SQ follows the POINTW, 
the record after the NOTEd record is written (or over- 
written) and, on CKD DASD, the remainder of the 
track is erased (overwritten with zeros). On PBA 
devices, the remainder of the CI is erased 
(overwritten with zeros) and an seof is written (the 
following CI is also overwritten with zeros). 
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PRTOV Macro 



Name Operation Operand 



[name] PRTOV 



(filename|(l)},(9112} 
[,routine-name|,(0)] 



The PRTOV (printer overflow) macro is used with a 
printer file to specify the operation to be performed 
when a carriage overflow condition occurs. To use 
this macro, the PRINT0V=YES operand must be in- 
cluded in the DTFPR or dtfsr. 

PRTOV requires either two or three parameters. 
The first parameter must be the filename, written 
either as a symbol or in register notation. The sec- 
ond parameter must specify the number of the car- 
riage control channel (9 or 12) used to indicate the 
overflow. When an overflow condition occurs, IOCS 
restores the printer carriage to the first printing line 
on the form (channel 1), and normal printing contin- 
ues. 

The third parameter is required if you prefer to 
branch to your own routine on an overflow condi- 
tion, rather than skipping directly to channel 1. It 
specifies the name of the routine, as a symbol or in 
register notation. However, the name should never 
be preloaded into register 1. 

If you specify the third parameter, IOCS does not 
restore the carriage to channel 1. 

PUT Macro 

Name Operation Operand 



[name] PUT 



{filename|(l)} 
[,workname|,(0)] 
,STLSP= (controlfieldl(r)} 
,STLSK= {controlfieldl(r)) 



PUT writes, prints, or punches logical records which 
are built directly in the output area or in a specified 
work area. PUT can be used for any sequential out- 
put file defined by a dtp macro, and for any type of 
record: blocked or unblocked, fixed or variable 
length, and undefined. It operates much the same as 
GET but in reverse. It is issued after a record has 
been built. 

filename: This operand is required. The parame- 
ter value must be the same as specified in the header 
entry of the DTP for the file being built. The ope- 
rand can be specified as a symbol or in either special 
or ordinary register notation. Use register notation 
if your program is to be self-relocating. 



workname: An optional parameter specifying the 
work area name or a register (in either special or 
ordinary register notation) containing the address of 
the work area. The work area address should never 
be preloaded into register 1. This parameter is used 
if records are built in a work area which you define 
yourself (for example, using a DS instruction). If the 
operand is specified, all puts to the named file must 
use a register or a workname. Using the second ope- 
rand causes PUT to move each record from the work 
area to the output area. 

Individual records for a logical file may be built 
in the same work area or in different work areas. 
Each PUT macro specifies the work area where the 
completed record was built. However, only one 
work area can be specified in any one PUT macro. 

Whenever a PUT macro transfers an output data 
record from an output area (or work area) to an I/O 
device, the data remains in the area until it is either 
cleared or replaced by other data. IOCS does not 
clear the area. Therefore, if you plan to build anoth- 
er record whose data does not use every position of 
the output area or work area, you must clear that 
area before you build the record. If this is not done, 
the new record will contain interspersed characters 
from the preceding record. 

STLSP=control field: This optional operand 
specifies a control byte that allows for spacing while 
using the selective tape listing feature on the 1403 
printer. To use this feature, the operand stlst=yes 
must be specified in the dtfpr. Up to 8 paper tapes 
may be independently spaced. The control byte is 
set up like any other data byte in virtual storage. 
You can also use ordinary register notation to pro- 
vide the address of the control byte. Registers 2 
through 12 are available without restriction. You 
determine the spacing (which occurs after printing) 
by setting on the bits corresponding to the tapes you 
want to space. The correspondence between control 
byte bits and tapes is as follows: 



Control byte bits 





1 


2 


3 


4 


5 


6 


7 


Tape position 


8 


7 


6 


5 


4 


3 


2 


1 



The tape position 1 is the leftmost tape on the selec- 
tive tape listing device. 

Note: Double-width tapes must be controlled by both bits of the 
control field. 

STLSK=control field: This optional operand 
specifies a control byte that allows for skipping 
while using the selective tape listing feature on the 
1403 printer. To use this feature, the operand 
STLIST=YES must be specified in the DTFPR. Up to 8 
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paper tapes may be independently skipped. The 
control byte is set up like any other data byte in 
virtual storage. You can also use ordinary register 
notation to provide the address of the control byte. 
Registers 2 through 12 are available without restric- 
tion. You determine the skipping (which occurs 
after printing) by setting on the bits corresponding 
to the tapes you want to skip. The correspondence 
between control byte bits and tapes is shown in the 
figure under "STLSP=control field", above. 

PUTR Macro 

Name 0»*erat!on Operand 



[name] PUTR 



{filename|(l)} 

[, {worknamel|(0)}, 

(workname2|(2)}] 



The PUTR (PUT with reply) macro is used for the 
display operator console, to issue a message to the 
operator which requires operator action and which 
will not be deleted from the display screen until the 
operator has issued a reply. 

You may also use PUTR with the 3210 or 3215 
console printer-keyboard, in which case PUTR func- 
tions the same as PUT followed by get for these 
devices, but provides the message non-deletion code 
for the display operator console. Use of PUTR for 
the 3210 or 3215 is therefore recommended for com- 
patibility if your program may at some time be run 
on the display operator console instead of the 3210 
or 3215. 

Use PUTR for fixed unblocked records (messages). 
Issue PUTR after a record has been built. 

filename: This operand is required. The parame- 
ter value must be the same as specified in the header 
entry of the dtfcn for the file being built. The fi- 
lename can be specified as a symbol or in either 
special or ordinary register notation. The latter is 
necessary to make your programs self-relocating. 

worknamel 1(0): An optional parameter specifying 
the output work area name or a register (in either 
special or ordinary register notation) containing the 
address of the output work area. The work area 
address should never be preloaded into registers 1 or 
2. This parameter is used if records are built in a 
work area which you define yourself (for example, 
using a DS instruction). The length of the work area 
is defined by the blksize parameter of the DTFCN 
macro. If worknamel is specified. workname2 must 
also be specified. 



workname2|(2): An optional parameter specifying 
the input work area name or a register (in either 
special or ordinary register notation) containing the 
address of the input work area. The work area ad- 
dress should never be preloaded into registers or 1 . 
This parameter is used if records are built in a work 
area which you define yourself (for example, using a 
DS instruction). The length of the work area is de- 
fined by the INPSIZE parameter of the dtfcn macro. 
If workname2 is specified, worknamel must also be 
specified. 



RDLNE Macro 


Name Operation 


Operand 


[name] RDLNE 


(filenamel(l)} 



The RDLNE macro provides selective on-line correc- 
tion when processing journal tapes on the 1287 opti- 
cal reader. This macro reads a line in the on-line 
correction mode while processing in the off-line 
correction mode. RDLNE should be used in the 
COREXIT routine only, or else the Une following the 
one in error will be read in on-line correction mode. 

If the 1287 cannot read a character, iocs first 
resets the input area to binary zeros and then retries 
the line containing the character that could not be 
read. If the read is unsuccessful, you are informed 
of this condition via your error correction routine 
(specified in dtfor corexit). The rdlne macro 
may then be issued to cause another attempt to read 
the line. If the character in the line still cannot be 
read, the character is displayed on the 1287 display 
scope. The operator keys in the correct character, if 
possible. If the operator cannot readily identify the 
defective character, he may enter the reject charac- 
ter in the error line. This condition is posted in 
filename+80 for your examination. Wrong-length 
records and incomplete read conditions are also 
posted in filename-l-80. 

This macro requires only one parameter, the sym- 
bolic name of the 1287 file from which the record is 
to be retrieved. This name is the same as that speci- 
fied in the DTFOR header entry for the file. 
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READ Macro 



Name Operation Operand 



[name] READ (filenamel (1)} 

{,SQ,{area|(0))[,length|.(r)lS]| 

,KEY| 

,OR, (namel (r)} | 

,ID| 

,DR, {name| (r) |number,number} | 

,MR} 



The READ macro transfers a record or part of a re- 
cord from an input file to an area in virtual storage. 

niename| (1): Specifies the name of the file from 
which the record is to be read. The name is the same 
as that specified in the DTP header entry. 

SQ: Required for sequential files. 

area| (0): The name of the input area used by a 
sequential file. 

length| (r) | S: Used only for sequential files of 
undefined format (recform=undef). Specifies the 
actual number of bytes to be read, or the register 
where the number is to be found. S specifies that the 
entire record is to be read. 

KEY: For ISAM, KEY is required. For DAM, speci- 
fies that the record reference is to be by record key 
(control information in the key area of the DASD 
record). 

OR: Signifies that the file is for a 1287 or 1288 
optical character reader. 

name I (r): Specifies the ccw list address to be 
used to read a document from the 1287 or 1288. 

ID: For DAM, specifies that the reference is to be 
by ID (identifier in the count area of the record). 

DR: Indicates a 3886 Optical Character Reader is 
the input device. 

The third parameter specifies the line number to 
be read and the format record for the line in one of 
three ways: 

• name| (r) provides the symbolic address of a 
2-byte hexadecimal field containing the line 
number in the first byte and the format record 
number in the second byte. 

• (r) provides the number of the register that 
contains the address of the two-byte hexadeci- 
mal field. 



• number,number provides the decimal line num- 
ber to be read (any number from 1 through 33), 
followed by the format record number used to 
reaad the line (0-63). 

MR: signifies that the file is for a magnetic ink 
character reader (MICR). 

RELSE Macro 

Name Operation Operand 



[name] RELSE 



{filename|(l)) 



The RELSE (release) macro is used with blocked 
input records read from a DASD device, or with 
blocked spanned records read from, or updated on, 
a DASD device. This macro is also used with blocked 
input records read from magnetic tape. 

The macro allows you to skip the remaining re- 
cords in a block and continue processing with the 
first record of the next block when the next GET 
macro is issued. When used with blocked spanned 
records, RELSE makes the next GET skip to the first 
segment of the next record. 

The symbolic name of the file, specified in the 
DTP header entry, is the only parameter required for 
this macro. It can be specified as a symbol or in 
register notation. 



RESCN Macro 



Name Operation Operand 



[name] RESCN 



(filename|(l)} 
,(rl),(r2),[nl][,n2] 



The RESCN macro selectively rereads a field on a 
document if one or more defective characters make 
this type of operation necessary. The field is always 
right-justified into the area (normally within 
lOAREAl) that was originally intended for this field 
as specified in the ccw. The macro first resets this 
area to binary zeros. 

Note: Por the 1287 models 3 and 4 and the 1288, this macro can 
only be used with READ BACKWARD commands. If used with 
READ PORWARD commands, the input area is not cleared. 
When 1288 unformatted fields are read, the RESCN macro 
should not be used. 

The first parameter, filename, specifies the sym- 
bolic name of the 1287D file as specified in the 
DTPOR header entry for the file. 

The second parameter, rl, specifies a general- 
purpose register from 2 to 12 into which the pro- 
gram places the address of the load format ccw. 
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The third parameter, r2, specifies a general- 
purpose register from 2 to 12 into which the pro- 
gram places the address of the load format ccw for 
reading the reference mark. 

The previous three parameters are always re- 
quired, and result in one attempted reread for the 
field. 

The fourth parameter, ni, allows you to specify 
the number of attempts (one to nine allowed) to 
reread the unreadable field. If this parameter is 
omitted, one is assiimed. 

The fifth parameter, n2, indicates one more re- 
read which forces on-line correction of any unreada- 
ble character(s) by individually projecting the un- 
readable character(s) on the 1287 display scope. 

The operator must key in a correction (or reject) 
character(s). This operand cannot be used for 1288 
processing. 

SECTVAL Macro 

Name Operation Operand 

[name] SECTVAL [DDKR=(namel|(0)}] 
[,DVCTYP=name2] 



The SECTVAL macro calculates the sector value of 
the address of the requested record on the track of a 
disk storage device when RPS is used. The macro 
returns this value in register 0. 

The sector value is calculated from data length, 
key length, and record number information. Values 
are calculated for fixed or variable length and for 
keyed and non-keyed records. 

DDKR= (nainel|(0)}: The information needed to 
calculate the sector value should be specified in the 
4-byte field at name 1 , or in the specified register. If 
no operand is specified, register is the default and 
should contain the necessary information. The four 
bytes of information have the format DDKR, where 

DD= a 2-byte field which specifies: 

• for fixed length records, the data length of each 
record, or 

• for variable length records, the number of bytes 
used on the track, excluding standard RO length 
up to the current record. Bit of the first byte 
must be set on. 

K= a 1-byte field indicating the key length: 

• for fixed length records, the actual key length 
must be specified; 

• for variable length records, any non-zero value 
is sufficient to indicate the presence of keys. 

Note: For non-keyed records the value should be 0. 



R= a 1-byte record number field which specifies 
the number of the record of which the sector 
value is being requested. 

DVCTYP=name2: The device type code is speci- 
fied at name2. If no operand is specified, it is as- 
sumed that byte of register 1 contains the code. 
The following device type codes (which are the same 
as the device type codes generated in the DTP) are 
valid for: 

IBM 3330, models 1 and 2: X'04' 
IBM 3330, model 1 1 : X'OS' 

IBM 3340: X'08', X'09', or X'OA' 
IBM 3350: X'OV 

The calculated sector value is returned in register 
0. If any errors are detected in calculating the sector 
value, a no-operation sector value (X'FF') is returned. 

SEOV Macro 

Name Operation Operand 



[name] SEOV 



filename 



The SEOV (system end-of- volume) macro must only 
be used with physical iocs to automatically switch 
volumes if SYSLST or SYSPCH are assigned to a tape 
output file. SEOV writes a tapemark, rewinds and 
unloads the tape, and checks for an alternate tape. If 
none is found, a message is issued to the operator 
who can mount a new tape on the same drive and 
continue. If an alternate unit is assigned, the macro 
fetches the alternate switching routine to promote 
the alternate unit, opens the new tape, and makes it 
ready for processing. When using this macro, you 
must check for the end-of- volume condition in the 
CCB. 



SETDEV Macro 



Name Operation Operand 



[name] SETDEV 



{filename|(l)} 
, {phasename|(r)} 



The SETDEV macro changes format records during 
execution of the program. When the new format 
record has been loaded into the 3886, control returns 
to the next sequential instruction in your program. 
If the operation is not successful, the completion 
code is posted at EXITIND and control is passed to 
the COREXIT routine, or the job is canceled. If you 
issue the SETDEV macro and no documents remain 
to be processed and the end-of-file key has been 
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pressed on the device, control is passed to the end- 
of-file routine. 

The first parameter, filename, specifies the same 
name as that used in the dtfdr header entry. Reg- 
ister notation must be used if your program is to be 
self-relocating. 

The second parameter specifies the name of the 
format record to be loaded, phasename; or indicates 
the register containing the address of an 8-byte area 
that contains the phasename. 

SETFL Macro 

Name Operation Operand 



[name] SETFL 



{filenamel(O)} 



The SETFL (set file load mode) macro causes ISAM to 
set up the file so that the load or extension function 
can be performed. This macro must be issued when- 
ever the file is loaded or extended. 

When loading a file, SETFL preformats the last 
track of each track index. When extending a file, 
SETFL preformats only the last track of the last irack 
index plus each new track index for the extension of 
the file. This allows prime data on a shared track to 
be referenced even though no track indexes exist on 
the shared track. 

The name of the file loaded is the only parameter 
required for this macro and is the same as that speci- 
fied in the DTFIS header entry for the file. It can be 
specified as a symbol or in register notation. Regis- 
ter notation is necessary if your program is to be 
self-relocating. 

SETL Macro 

Name Operation Operand 



[name] SETL 



(filename|(r)} 

,{id-name|(r)|KEY|BOF| 

GKEY) 



The SETL (set limits) macro initiates the mode for 
sequential retrieval and initializes ISAM to begin 
retrieval at the specified starting address. The first 
operand (filename) specifies the same name as that 
used in the DTFIS header entry, as a symbol or in 
register notation. Register notation is necessary if 
your program is to be self-relocating. 

The second operand specifies where processing is 
to begin. 

If you are processing by the record ID, the ope- 
rand id-name or (r) specifies the symbolic name of 



the 8-byte field in which you supply the starting (or 
lowest) reference for ISAM use. This field contains 
the information shown in Figure 4-8. 

If processing begins with a key you supply, the 
second operand is KEY. The key is suppUed in the 
field specified by the DTFIS keyarg operand. If the 
specified key is not present in the file, an indication 
is given at filenamec. 

BOF specifies that retrieval is to start at the begin- 
ning of the logical file. 

Selected groups of records within a file contain- 
ing identical characters or data in the first locations 
of each key can be selected by specifying GKEY 
(generic key) as the second operand. GKEY allows 
processing to begin at the first record (or key) within 
the desired group. You must supply a key that iden- 
tifies the significant (high order) bytes of the re- 
quired group of keys. The remainder (or insignifi- 
cant) bytes of the key must be padded with blanks, 
binary zeros, or bytes lower in collating sequence 
than any of the insignificant bytes in the first key of 
the group to be processed. For example, a GKEY 
specification of D6420000 would permit processing to 
begin at the first record (or key) containing 
D642XXXX, regardless of the characters represented by 
the x's. Your program must determine when the 
generic group is completed. Otherwise, ISAM contin- 
ues through the remainder of the file. 

Note: If the search key is greater than the highest key on the file, 
the filename status byte is set to X'lO' (no record found). 

The ESETL (end set limit) macro should be issued 
before issuing a READ or write if addrtr and/or 
RANDSEQ are specified in the same DTF. Another 
SETL can be issued to restart sequential retrieval. 
Sequential processing must always be terminated by 
issuing an ESETL macro. 

TRUNC Macro 

Name Operation Operand 



[name] TRUNC 



{filename|(l)} 



The TRUNC (truncate) macro is used with blocked 
output records written on dasd or magnetic tape. It 
allows you to write a short block of records. Blocks 
do not include padding. Thus, the TRUNC macro 
can be used for a function similar to that of the 
RELSE macro for input records. That is, when the 
end of a category of records is reached, the last 
block can be written and the new category can be 
started at the beginning of a new block. 

Note that if DEVICE=FBA is specified on the DTF, 
TRUNC will not necessarily cause a physical write to 
the FBA DASD unless pwrite is also specified. 
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Byte 


Identifier 


Contents in Hexadecimal 


Information 





m 


02-F5 


Number of the extent in which the starting record is located 


1-2 


bb 


0000 (disk) 


Always zero for disk 


3-4 


cc 


0000-00C7 (231 1 , 231 4, 231 9) 
0000-01 93 (3330, 3333) 
0000-01 5B (3348 model 35) 
0000-02B7 (3348 model 70) 


Cylinder number for disk: 

for 2311, 2314, 2319:0-199 

for 3330, 3333: 0-403 

for 3340 with 3348 model 35: 0-347 

for 3340 with 3348 model 70: 0-695 


5-6 


Mil 


0000-0009 (2311) 
0000-0013(2314, 2319) 
0000-001 2 (3330, 3333) 
0000-0008 (3340) 


Head position for disk 


7 


r 


01 -FF 


Record location 



Figure 4-8. Field supplied for SETL processing by record ID 

The symbolic name of the file, specified in the 
DTF header entry, is the only parameter required in 
this macro. 



WAITMacro 

Name Operation Operand 



[name] WAIT {blockname|(l)} 



Issue this macro whenever your program requires 
that an I/O operation (started by an EXCP macro) be 
completed before execution of the program contin- 
ues. For example, transferring data (a physical re- 
cord) to virtual storage must be completed before 
data can be added or moved to another area of vir- 
tual storage, or otherwise processed. When wait is 
executed in a batched job environment, processing is 
suspended until the traffic bit (byte 2, bit 0) of the 
related CCB or lORB is turned on. Then, processing 
automatically continues and the data can be proc- 
essed. In a multiprogramming environment, the 
supervisor gives control to another program, until the 
traffic bit is set on. 

The blockname (specified as a symbol or in regis- 
ter notation) of the CCB or lORB estabhshed for the 
I/O device is the only operand required. This is also 
the same name as that specified in the EXCP macro 
for the device. 

WAITF Macro 

Name Operation Operand 



devices. Filename is the same as that used in the 
DTP header entry, and may be specified either as a 
symbol or in register notation. Note that multiple 
filenames are valid only when using SAM to read 
MICR records. 

The WAITF macro is issued after any read or 
WRITE for a file and before the succeeding READ or 
WRITE for the same file. If the I/O operation is not 
completed when WAITF is issued, the active partition 
is placed in a wait state until the data transfer is 
completed. This allows processing of programs in 
other partitions while waiting for completion. When 
data transfer is complete, and if no errors were en- 
countered, processing continues with the next se- 
quential instruction. If an error is encountered, con- 
trol passes to the error-handling routine provided for 
in the dtp. 

If, however, you are using the multiple filename 
format of the WAITF macro while using MICR re- 
cords, and if any of the files have records or errors 
ready to be processed, control remains in the parti- 
tion and processing continues with the instruction 
following the WAITF. 

WRITE Macro 

Name Operation Operand 



[name] WRITE 



[name] WAITF 



{filename I |(rl)} 
[,filename2|,(r2)] 



{filename|(l)} 

{, (SQIUPDATE) , (area|(0)} i 

[,length|,(r)]| 

,KEY| 

,ID| 

,AFTER[,EOF]| 

,NEWKEY| 

,RZERO} 



The WAITF macro is issued to ensure that the trans- 
fer of a record is complete. It is vaUd for both dam 
and ISAM, but for SAM only with MICR and OCR 



The WRITE macro transfers a record from virtual 
storage to an output file. 
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filename|(l): Filename specifies the same name as 
that used in the DTF header entry. Register notation 
must be used if your program is to be self-relocating. 

SQIUPDATE: For sequential files, specify SQ for 
magnetic files, or for disk work files for a formatting 
write (count, key, and data). Specify update for a 
non-formatting write (data only). 

area|(0): For sequential files, specifies the name, 
as a symbol or in register notation, of the output 
area used by the file. 

length|(r): Specifies the actual number of bytes to 
be written on a sequential file. Is used only for re- 
cords of undefined format (recform=undef). 

KEY: For indexed sequential files, specify KEY for 
random updating. For direct access files, specify 
KEY to write in a location determined by the record 
key (control information in the key area of the re- 
cords). 



ID: For DA files, specify ID to write in a location 
determined by the record identifier in the count area 
of the records. 

AFTER: For DA files, specify after to write a 
record after the last record written, regardless of key 
or identifier. 

EOF: Optional: applies only to the WRITE. ..after 
form of the macro. Specify to write an end-of-file on 
a track after the last record on the track. 

NEWKEY: For indexed sequential files only; 
specify NEWKEY to write a new (not updated) record 
in the file. When loading or extending the file, pre- 
ceed the write filename,NEWKEY with a setfl 
macro and follow it with an endfl macro. When 
adding a record after sequential retrieval, issue an 
ESETL macro before writing the record. 

RZERO: For DA files, specify RZERO to reset the 
capacity record of a track to its maximum value and 
erase the track after record zero. 
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ATTACH Macro 



Save area without floating-point option: 



Name Operation Operand 



[name] ATTACH (entrypomt|(S,entrypoint)|(rl)} 

,S AVE= {savearea|(S,savearea) | (r2)] 
[,ECB= {ecbname|(S,ecbname)|(r3)} ] 
[,ABSAVE= {savearea|(S,savearea)|(r4)} ] 
[,MFG= {area|(S,area)|(r5)) ] 



A subtask can be intitiated only by issuing the 
ATTACH macro within the main task. The part of 
the subtask containing the entry point must be in 
storage before the subtask can be successfully atta- 
ched. 

If register notation is used in any of the macro 
operands, register and 1 should not be specified. 

entrypoint |(S,entrypoint)|(rl): The operand 
specifies the entrypoint of the subtask. 

SAVE=(savearea|(S, savearea)|(r2): The ope- 
rand must provide the address of the save area for 
the subtask. The save area is 96 or 128 bytes in 
length depending upon whether or not the supervi- 
sor provides floating-point support (for S/370 mode, 
FP=YES must have been specified in the CONFG gen- 
eration macro). 

If an interrupt occurs while the subtask is in con- 
trol, the system saves in this save area the subtask's 
interrupt status information, general purpose regis- 
ters, and (depending on floating-point support) the 
floating-point registers (see Figure 5-1). 

Before issuing the attach macro, provide a sub- 
task name in the first eight bytes of the save area. 
The name is used to identify the subtask in the event 
of a possible abnormal termination condition. 

ECB= {ecbname|(S,ecbname)|(r3)}: The operand 
must be specified if other tasks can be affected by 
this subtask's termination, or if the ENQ and DEQ 
macro are used within the subtask. This parameter 
is the name of the subtask's event control block 
(ECB), and is a fullword defined within your pro- 
gram. The ECB may be any 4-byte (or larger) field 
where in byte 2, bit is the termination indicator 
and bit 1 is the abnormal indicator. The remaining 
bits of the four bytes are reserved. At the time a 
subtask is attached, bits and 1 of byte 2 are set to 0. 
When a subtask terminates, the supervisor sets byte 
2, bit of the ECB to 1. In addition, byte 2, bit 1 is 
set to 1 when the subtask terminates abnormally; 
that is, if task termination is not the result of issuing 
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Figure 5-1. Subtask save area. 

the CANCEL, DETACH, DUMP, or EOJ macros. 

ABSAVE= {savearea|(S,savearea)|(r4)} : Specify 
this operand only if the subtask is to use the main 
task abnormal termination routine (see STXIT ma- 
cro), that is, if it does not provide an abnormal ter- 
mination routine of its own. Your program can have 
separate subtask STXIT ab routines with or without a 
main task STXiT AB routine, or it can have neither. 
The parameter specified in this operand must be the 
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address of a 72-byte (doubleword-aligned) STXIT 
save area for the subtask. When an abnormal termi- 
nation occurs, the supervisor saved the old PSW and 
general registers through 15 in this area before the 
exit is taken. 

MFG= {area|(S,area)|(r5)} : The operand is re- 
quired if the program which issues the attach ma- 
cro is to be reenterable. It specifies the address of a 
64-byte dynamic storage area, that is, storage which 
your program obtained through a getvis macro. 
This area is required for system use during execu- 
tion of the macro. 

If the ATTACH macro successfully initiates a sub- 
task, the subtask is given higher priority than the 
main task, and control passes to the subtask. Regis- 
ter 1 of the subtask contains the address of the main 
task save area, and the contents of the main task 
registers 2 through 15 remain as they were prior to 
issuing the attach; they are also passed to the ap- 
propriate fields in the subtask save area. The ad- 
dress in register 1 can be used as the second operand 
of a POST macro later in the job if task-to-task com- 
munication is desired. Upon return from a success- 
ful attach, the main task register contains the 
address of the byte immediately following the sub- 
task save area, as determined by the supervisor. 
Register therefore can be tested to ascertain 
whether the supervisor contains the floating-point 
option. 

The maximum possible number of subtasks is 
determined by subtracting the number of partitions 
from the number 15. For example, the maximum 
possible number of subtasks is 13 for a 2-partition 
system or 10 for a 5 -partition system. In the event 
that the maximum possible number of subtasks is 
already attached, any attempt to attach another sub- 
task will be unsuccessful. In this case, the main task 
will keep control and register 1 (main task) will con- 
tain the address of an ECB within the supervisor that 
will be posted when the system can initiate another 
subtask. Register 1 will also have the bit on to aid 
the main task in testing for an unsuccessful attach. 

Note: If your program uses VSAM files, you should provide a 
STXIT AB and PC macro and issue a CLOSE or TCLOSE for 
the files before canceling the subtask. 

CALL Macro 

The format of the CALL macro is: 

Name Operation Operand 

[name] CALL (entrypoint|(i5)} 

[,(parameterlist)] 



The CALL macro passes control from one program to 
a specified entry point in another program. 

entrypoint|(15): specifies the entry point to which 
control is passed. If the symbolic name of an entry 
point is specified, an instruction 
L 15,=V(entrypoint) 

is generated as part of the macro expansion. The 
linkage editor makes the called program part of the 
calling program phase. The symbolic name must be 
either the name of a control section (CSECT) or an 
assembler language entry statement operand in the 
called program. Control is given to the called pro- 
gram at this address. The called program resides in 
storage throughout execution of the calling program. 
This wastes storage if the called program is not 
needed throughout execution of the calling program. 

If register 15 is specified, the entrypoint address 
must have been loaded into that register. Control is 
given to the called program at the address in register 
15. Specifying register 15 preceded by a load ma- 
cro is most useful when the same program is called 
many times during execution of the calling program, 
but is not needed in storage throughout execution of 
the calling program. 

parameterlist: specifies one or more addresses 
(relocatable or absolute expressions) to be passed to 
the called program. Terms in the address must not 
be indexed. The addresses must be written in a sub- 
list, with each address separated from the next by a 
comma. As part of the macro expansion, a parame- 
ter list is generated. It consists of a fuUword for each 
address. Each fuUword is aligned on a fuUword 
boundary and contains the address to be passed in 
its three low-order bytes. The high-order bit in the 
last fuUword is set to 1 . When the called program is 
entered, register 1 (the parameter list register) con- 
tains the address of the parameter list. 

CANCEL Macro 

Name Operation Operand 



[name] CANCEL [ALL] 



Issuing the cancel macro in a subtask abnormally 
terminates the subtask without branching to any 
abnormal termination routine. A cancel all ma- 
cro issued in a subtask, or a CANCEL issued in the 
main task, abnormally terminates all processing in 
the partition (job). Job termination in multitasking 
causes all abnormal termination exits (via stxit ab) 
to be taken for each task except the one that issued 
the CANCEL macro. Once these exits are taken, the 
job is terminated. Upon task termination, system 
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messages (using the first eight bytes of each subtask 
save area) are issued to identify each subtask termi- 
nated. 

If the CANCEL macro is issued without an ope- 
rand, the macro must not contain a comment unless 
the comment begins with a comma. If cancel all 
is issued, the macro may include a comment. 

If the DUMP option was specified, and SYSLST is 
assigned, a system dump will occur 

• if a CANCEL ALL macro is issued by a subtask, 
or 

• if a CANCEL macro is issued by a main task 
with subtasks attached. 

CDLOAD Macro 

Name Operation Operand 



[name] CDLOAD 



{phasename|(l)} 

[,PAGE={NO|YES}] 

[,RETPNF=(NO|YES}] 



The CDLOAD macro loads the phase specified in the 
first parameter from the core image library into the 
partition GETVIS area. The phase is loaded only if it 
is not yet in either the partition GETVis area or the 
SVA. CDLOAD returns control to the phase which 
issued the macro. 

The CDLOAD macro must not be used for a phase 
that has been linked as a member of an overlay 
structure. Instead, use the load macro without 
specifying a load address. 

If a phase is to be loaded, CDLOAD determines the 
size of the phase, acquires the appropriate amount 
of GETVIS storage, and loads the phase into that 
storage. 

After successfully loading the phase or if loading 
is not required (because the phase is already in the 
partition getvis area or in the SVA), registers con- 
tain values as follows: 

register 0: the load address, 
register 1 : the entry point, 
register 14: the length of the phase. 

phasename: For phasename, specify the name of 
the required phase. If register notation is used, the 
register must contain the address of an 8-byte field 
that holds the phase name as an alphameric charac- 
ter string. 

Page= {NOjYES}: If you want to have the phase 
loaded on a page boundary, specify page=yes. 

RETPNF= {NOjYES} : determines whether the 



issuing phase is canceled if the phase to be loaded 
does not exist in the core image library. With 
retpnf=yes, the phase is not canceled; instead, 
control is returned to the issuing phase with the ap- 
propriate return code. 

Return Codes in Register 15 

After execution of the macro, register 1 5 contains 
one of the following return codes: 

CDLOAD completed successfully. 
4 The size of the partition's GETVis area is OK. 
8 The length of requested GETVis storage is nega- 
tive. 
12 No more storage is available in the getvis 

area. 
16 The partition CDLOAD directory (also known as 

anchor table) is full. 
20 The phase does not exist in the core image li- 
brary (this return code occurs only with 
retpnf=yes). 
32 A hardware (storage) failure occured in the 
requested real partition getvis area. 

CHAP Macro 

Name Operation Operand 

[name] CHAP 



The CHAP macro lowers the priority of the issuing 
subtask. This issuing subtask now becomes the sub- 
task with the lowest priority of all the subtasks with- 
in the partition. 

A CHAP macro issued by the main task is ignored. 

The supervisor must have been generated with 
multitasking support, otherwise the task issuing the 
CHAP macro will be canceled. 



CHKPT Macro 

Name Operation Operand 



[name] CHKPT 



SYSnn, {restart-address|(rl)} 

[,end-address|,(r2)] 

[,tpointer|,(r3)] 

[,dpointer|,(r4)] 

[,filename|,(r5)] 



The CHKPT macro is used to record the status of 
your program so that the program, should its execu- 
tion be terminated before it has completed process- 
ing, may be restarted using job control. The parti- 
tion in which the program is to be restarted must 
start at the same location as when the program was 
checkpointed, and its end address must not be lower 
than the end address at checkpoint time. If the 
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CHKPT macro is successfully executed, control is 
returned with the checkpoint number in unpacked 
decimal format in register 0. If it is unsuccessful and 
the checkpoint has not been taken, register con- 
tains zero and the reason is printed on SYSLOG. 

Note: If a program using routines in the SVA is being check- 
pointed, you must make sure that SVA routines occupy the same 
locations on restart, should a restart become necessary. 

Special register notation cannot be used with any 
of the CHKPT macro operands. 

All VSAM files should be closed before the CHKPT 
macro is issued. 



SYSnnn; Specifies the logical unit on which the 
checkpoint information is to be stored. It must be an 
EBCDIC magnetic tape or a disk pack. 

restart address|(rl): Specifies a symbolic name of 
the instruction (or register containing the address) at 
which execution is to restart if processing must be 
continued later. 



COMRG Macro 



Name Operation Operand 



[name] COMRG 



REG = rl 



The COMRG macro places the address of the com- 
munication region of the partition from which the 
macro is issued into the specified register. If the 
operand is omitted, register 1 is assumed. 



CPCLOSEMacro 



Name Ope r attoa Q^ | >eraiid 



inamel CPCLOSE farelisttfrni 



In Spooling programs written m Basic Assembler 

Language, the cpclosb macro can be used to issue a 

cp CLOSE command to VM/370 in order to release a 
print or punch iile for output. 

Notet The CPCLOSE tnacf a is v^lid oidy with a DOS/VSE 
s^yst«m with VSE/Advanced Functicjns iostalled and a superviso^r 
generated with the VM« Y£S ojption specified on the SUPVR 



end address|(r2): A symbolic name assigned to (or 
register containing the address of) the uppermost 
byte of the program area required for restart. This 
address must be higher than the highest address of 
storage occupied by any phase loaded into the parti- 
tion. The address should be a multiple of 2K. If the 
address is not a multiple of 2K, it is rounded to the 
next 2K boundary. If this operand is omitted, all 
storage allocated to the partition (other than the 
GETVis area) is checkpointed. 

The specified end address is ignored if any 
GETVis was executed in the partition. (Note that 
GETVTS storage may have been requested by includ- 
ed IBM routines). In this case again, all storage allo- 
cated to the partition is checkpointed. 

tpointer|(r3): Address of an 8-byte field containing 
2 v-type address contants used in repositioning mag- 
netic tape at restart time. The address may be a 
symbolic address or contained in a register. For 
details, see the section "Repositioning Magnetic 
Tape" in the DOS/ VSE Macro User's Guide. 



argUst|(rl): This operand specifies a 16-byte argu- 
ment list whose format is described below and which 
must be set up before issuing the macro. If the argu- 
ment list name is specified^ EX>s/vsE loads the ad- 
dress into register I . If a register is specified, it is 
assumed to contain the address of the argument list 
and this address is loaded into register I, If no ope- 
rand is specified, register 1 is assumed to contain the 
address of the argument list. 



Packed device 
addre^ 



EBCDIC 

device address 



Job nam« 







15 



pAckcd ucvicc jidutess "^ imii record device address of the device 

to be closed <in packed format), 
EBCDIC device address — «tiii record device address of ibe 

device to tw closed (in EBCDIC format). 

Job name — jjanje of the^job. 



Return codes in Register 15 

x^'-SiiccessM £S3mpletion of cpclose macro. 

X'04 -Device is invalid, no close is issued, 
X'OS'-VM=yES support not included in. the supervisor. 



dpointer|(r4): Address of a DASD operator verifica- 
tion table, used to allow the operator to verify dasd 
volume serial numbers at restart time. May be a 
symbolic address or contained in a register. 



DEQ Macro 




Name Operation 


Operand 


[name] DEQ 


(rcbnameKO)) 



filename|(r5): The name of the associated DTFPH; 
used only for checkpoint records on disk. 



A task releases a resource by issuing the DEQ macro. 
If other tasks are enqueued on the same rcb, the 
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DEQ macro frees from their wait condition all other 
tasks that were waiting for that resource. In such 
cases, the highest priority task either obtains or 
maintains control. A task that attempts to dequeue a 
resource that was not enqueued or that was en- 

Sueued by another task is abnormally terminated. 
)equeuing under these two conditions within an 

abnormal termination routine results in a null oper- 
ation instruction. 

rcbname|(0): The operand is the same as that in 
the ENQ macro and specifies the address of the RCB. 

DETACH Macro 

Name Operation Operand 

[name] DETACH [SAVE=(savearea|(l)]] 

The DETACH macro terminates execution of a task. 
A subtask is normally terminated by issuing a 
DETACH macro, and no operand is required in this 
case. The main task can also terminate a subtask it 
initiated by issuing the DETACH macro with an ope- 
rand. The operand provides the address of the save 
area specified in the attach macro for the subtask 
to be terminated. If the main task issues the detach 
macro without specifying an operand, all programs 
in the partition are terminated abnormally. The 
DETACH macro sets byte 2, bit of the ECB to 1 (if 
specified in the attach macro) to indicate normal 
termination. All tasks waiting on this ECB are taken 
out of the wait state, and the highest priority task 
obtains control. 

Note: If your program uses VSAM files, ensure that these files 
are closed before you issue this macro. 

DTL Macro 

Naoie C^>eration Qperand 



te] DLT 



[NAM£=fesourceoattie| 

[,CONTROL=(EjS}] 

|,LOCKOPT={l|2}] 

|,KEEP==tl^lYE$}| 

t^OWKER^ gASKJPARTITION}] 



The DLT (Define The Lock) macro generates a con- 
trol block which is used by the lock/unlock mac- 
ros to enqueue/dequeue a resource access request. 
The control block, commonly called 'DLT% is gener- 
ated at the time of program assembly. 

NAMEssresoureename: specifies the name by 
which the resource is known to the system for the 
purpc^e of access share control. It is by this name, 
that DOS/VSE controls shared access of the resource 
as requested by active tasks via the LOCK macro. 



These tasks may all be active In one partition, or 
they may be distributed over several partitions; the 
resource-share control extends acro^ inanitions. 

The name may be up to twelve bytes long. 

CONTROL^: {E|S} : defines how the named re- 
source can be shared while your program owns It, 
which is determined by this specification and your 
spectflcation for the operand LOCKOUT. A specl^ca- 
tion of E means the resource is enqueued for exclu- 
sive use; a specification of s means the resource Is 
enqueued as sharable* 

LOCKOPTss (IJZ} ; This operand, together with 
the CONTROL parameter, determines how the system 
controls shared access In response to a lock request. 

* tOCKOPTs;^! and CONTROL-^E: no other task is 
allowed to use the resource concurrently. 

♦ LOCKOFr=i and control-S: other *S" users are 
allowed concurrent access, but no concurrent 'F 
user is alowed, 

* LOCKOPT=2 and control=E: no other "E' user 
gets concurrent access; however, other "S' users 
can have access to the resource. 

• lock:opt^2 and control=S: other 'S' users can 
have concurrent access and, in addition, one 'F 
user is allowed. 

KEEPas {H0| YES) : This operand may be used to 
lock the named resource beyond job step bounda- 
ries. Only a main task should use this operand. 
KEEP=MO indicates that the named resource once 
locked, is to fee rele^ied automatically at the end of 
the particular job step. With keep- yes, a named 
resource that is locked remains locked across job 
steps; it will be automa^cally released at end-of-job. 

OWNER« fTASKj PAltTITION] : defines 
whether the named resource, once locked, can be 
unlocked only by the task which issued the corre- 
sponding LOCK request (OWNER-TASK), or whether 
it can be unlocked by any task within the partition 

<OWNBR*PARTiTiON>, 

When OWNER is defined as PARTITION, a LOCK 
request for the resource must not specify fail^waft 
or FAIL-WAITC because deadlock prevention (return 
code 16) is not supported with OWNER^PARTmoK- 

DUMP Macro 

Name Operation Operand 

[name] DUMP 



This macro provides a hexadecimal dump of the 
following: 
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• The contents of the entire supervisor area and 
the used part of the system GETVIS area, or of 
some supervisor control blocks only (see Note 
below). 

• The contents of the partition that issued the 
macro. 

• The contents of the registers. 

Note: The dump includes the contents of some supervisor control 
blocks ouly, raihci than lac cilliic supci'visoi area if, the 
STDOPT job control command specifies DUMP=PART or NO, 
or if a job control statement //OPTION PARTDUMP or NO- 
DUMP is submitted. 

In addition, the macro causes the job step to be ter- 
minated if DUMP was issued by the main (or only) 
task of the program. If DUMP was issued by a sub- 
task, the macro causes that subtask to be detached 
without terminating the main task in the partition. 

The dump provided by the macro is always di- 
rected to SYSLST , which must be opened if disk or 
tape; if SYSLST is a tape, that tape must be posi- 
tioned as desired. 

If DUMP is issued by a job running in real mode, 
the storage contents of the partition are dumped 
only up to the limit as determined by the SIZE par- 
ameter of the EXEC job control statement, plus the 
storage obtained dynamically through the GETVis 
macro. If SIZE was not specified, the entire partition 
will be dumped. If DUMP is issued by a program 
running in virtual mode, the entire partition is 
dumped. 



ENQ Macro 




Name Operation 


Operand 


[name] ENQ 


{rcbname|(0)} 



A task protects a resource by issuing an ENQ 
(enqueue) macro. When the RCB, (identified by the 
rcbname) is enqueued, the task requesting the re- 
source is either queued and executed, or if the re- 
quested resource is held by another task, is placed in 
a wait condition. When the task holding that re- 
source completes, that task issues the DEQ (dequeue) 
macro. All other tasks that are then waiting for the 
dequeued resource are freed from their wait condi- 
tion, and the highest priority task either obtains or 
maintains control. 

If a task is terminated without dequeuing its 
queued resources, any task subsequently trying to 
enqueue that resource is abnormally terminated. If 
a task issues two ENQs without an intervening DEQ 
for the same resource, the task is canceled. Also, any 
task that does not control a resource but attempts to 
dequeue that resource is terminated, unless DEQ 
appears in the abnormal termination routine. If DEQ 



appears in the abnormal termination routine, it is 
ignored. 

Although the main task does not require the pro- 
gram to set up an intertask communication ECB to 
enqueue and dequeue, every subtask using that fa- 
cility must have the ECB operand in the attach 
macro, and that ECB must not be used for any other 
purpose. Also, a resource can be protected only 
within the partition containing the ECB. 

EOJ Macro 

Name Operation Operand 



Issue the EOJ macro in the main task or in the only 
program within a partition, to inform the system 
that the job step is finished. If a subtask issues an 
EOJ, the subtask is detached and the remainder of 
the partition continues. If the main task issues EOJ, 
all abnormal termination exits (via stxit ab) are 
taken for the subtasks still attached. 

EXIT Macro 

Name Operation Operand 

[name] EXIT {PC|IT|OC|AB|TT|MR} 



The EXIT macro is used to return control from your 
exit control or MR routine to the instruction in your 
interrupted program immediately after the instruc- 
tion where the interruption occurred. For ab, con- 
trol is returned to the instruction following the exit 
AB macro. Your routine is specified in the STXiT 
macro for MR, in the dtfmr macro. The operands 
have the following meanings: 

PC Exit from your program check routine. 

IT Exit from your interval timer routine. 

OC Exit from your routine which handles the op- 
erator attention interrupt. 

AB Exit from your abnormal task termination 
routine of your main task. 

TT Exit from your task timer routine. 

MR Exit from your stacker selection routine (MICR 
document processing) to the the supervisor. 

The EXIT macro should be issued only in the cor- 
responding (PC, IT, OC, AB, TT, MR) routine; a pro- 
gram check may occur if this rule is not observed. 

Detailed information on the save area and the 
interrupt status is given in DOS/VSE Serviceability 
Aids and Debugging Procedures,. 
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For PC, IT, oc, and TT, the interrupt status inform- 
ation and registers are restored from the save area; 
thus, the save area contents are not over-written. 

For AB, the cancel condition and abend indica- 
tion of the affected task are reset. The EXIT AB ma- 
cro may be used only in main tasks. In a subtask, it 
would result in an illegal SVC. You have to make 
sure that the abnormal termination condition has 
been cleared up by your abnormal task termination 
routine before using the EXIT AB macro. 

FCEPGOUT Macro 

You can code the macro in either of the following 
two formats: 

Name Operation Operand 

[name] FCEPGOUT begmaddr,endaddr 

[beginaddr, endaddr] . . . 

[name] FCEPGOUT {listname|(l)) 



The FCEPGOUT macro causes a specific area in real 
storage to be paged-out at the next page fault. This 
request is ignored if the specified area does not con- 
tain a fuU page. This can happen up to an area size 
of 4K minus 2 bytes (see Figure 5-2). 



X'OO' 


address constant 


length minus 1 







2k 



2k 



' 


— First byte ot page n 

Starting address of specified 
1 area (length = 4k-2 bytes) 

r 1 ' 








Hage n 






Page n-rl 








; I 1 

End address of specified area ' 

Last byte of page n + 1 


I 
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Figure 5-2. Worst case of an area not containing one full page. 

If your supervisor was geB«ratcd with vm-yes (in 
the SUPVR ge^n^fatioa macro), execation of tite ma- 
cro resitUs iU, a nml operatioo; tbe return code Is s«!t 
to z«ro. 

beginaddr: Points to the first location of the area to 
be paged out. 

endaddr: Points to the last location of the area to be 
paged out. 

listname|(l): Is the symbolic name of a list of con- 
secutive 8-byte entries as shown below. 



where: 

address constant = Address of the first byte of the 

area to be paged out. 
length = A binary constant indicating 

the length of the area to be 

paged out. 

A non-zero byte following an entry indicates the end 
of the list. Register notation may also be used. 

Exceptional Conditions 

The program is running in real mode. 

The page(s) referenced by the macro is (are) 
outside of the requesting partition. 

A page handling request is pending for the refer- 
enced page(s). 

The page(s) is (are) not in real storage. 

The page(s) is (are) fixed. 

For those pages the FCEPGOUT request will be 
ignored. 

The supervisor was not generated with 
PAGEiN=n in the SUPVR macro (in this case the pro- 
gram is canceled). 

Return Codes in Register 15 

All specified pages have been forced for page- 
out or the request has been ignored because the 
issuing program is running in real mode. 

2 The begin address is greater than the end ad- 
dress, or a negative length has been found. 

4 At least one of the requested pages does not 
belong to the partition in which the issuing pro- 
gram is running. The FCEPGOUT request has 
only been executed for those pages which be- 
long to the partition of the issuing program. 

8 a. At least one ofthe requested pages is tempo- 
rarily fixed (via ccw-translation) and/or 
PFiXed. The fcepgout request has only been 
executed for the unfixed pages, 
b. A page handling request (page fault, tempo- 
rary fix, PFIX) for at least one ofthe requested 
page is pending (caused by asynchronous proc- 
essing within a partition). The FCEPGOUT re- 
quest has not been executed for those pages 
which are involved in a page handling request. 

16 List of areas that are to be paged out is not 
completely in the requesting program's parti- 
tion. The request is ignored. 

Any combination of return codes 0, 2, 4, and 8 is 
possible. 
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FETCH Macro 



Name Operation Operand 



[name] FETCH {phasename|(S,address)| (1)} 

[,entrypoint|(S,entrypoint)| (0)] 
[,LIST= (listname|(S,listname)| (r)}] 
[,SYS=YES] 
[,DE=YES] 
[,MFG= {area|(S,area)|(r2)) ] 



The FETCH macro loads and gives control to the 
phase specified in the first parameter fi-om the core 
image library if this phase is not in the SVA. If the 
phase is in the SVA, it is not loaded into the partition, 
but control is given to the phase. For information on 
how to load phases into the sva and how to write 
SVA-eligible (reenterable) phases see DOS/VSE 
System Management Guide. 

phasename|(S,address)|(l): For phasename speci- 
fy the name of the required phase. 

If DE=YES is not specified, the address as speci- 
fied in (s, address) or as loaded into a register points 
to an 8-byte field that contains the phase name. If 
DE=YES, the operand has a different meaning; refer 
to the discussion of the DE operand. 

entrypoint|(S,entrypomt)|(0): Control is passed 
to the address specified by the entrypoint parameter. 
If this parameter is not specified or invalid, control 
is passed to the entrypoint determined at link-edit 
time. 

If entrypoint is given in register notation, register 
1 must not be used. You preload the register with 
the entrypoint address. 

With S-type notation, the entrypoint is derived 
from base register and displacement, e.g. (S, offset 
(reg)). If instead, a symbolic name is used for entry- 
point, the macro expansion results in a v-type ad- 
dress constant. The entrypoint does not have to be 
identified by an EXTRN statement. 

LIST={listname|(S,Iistname)|(rl)}: For list- 
name specify the name of your local directory Ust 
generated in the partition by the GENL macro. 
When this operand is included, the system scans the 
local directory list for the required phasename be- 
fore it initiates a search for this phase name in the 
pertinent core image library directory. 

S YS= YES: If SYS= YES is specified, the system 
scans the system directory list (SDL) in the sva and 
the system core image library before the private core 
image library (if a private CIL is assigned at all). If 



nothing is specified, the private CIL takes prece- 
dence. 

DE=YES: This operand is useful if your program, 
frequently fetches one specific phase. DE=YES is 
invalid if LIST is specified. 

DE=YES indicates that your program contains a 
34-byte field where you have placed a single directo- 
ry entry like those generated by the GENL macro. If 
this directory entry is active the directory scan 
mechanism is bypassed; if not, the entry will be 
filled in by the supervisor after which it is active. 

If the first operand is written as phasename 
(instead of S-type or register noiation) a directory 
entry will be generated within the macro expansion. 
The generated directory entry will contain the pha- 
sename in the first 8 bytes. If you specify DE=YES 
and if you use (S, address) or register notation for 
the first operand, you must set aside the 34-byte 
field yourself and point to it via this operand. The 
directory entry must contain the phase name in the 
first 8 bytes (left-justified and padded with blanks) 
and X'OB' at displacement X'OB'. 

MFG= (area|(S,area)|(r2)}: The operand mfg is 
required if the program which issues the fetch ma- 
cro is to be reenterable. It specifies the address of a 
64-byte dynamic storage area, that is, storage which 
your program obtained through a getvis macro. 
This area is required for system use during execu- 
tion of the macro. 

FREE Macro 

Name Operation Operand 



[name] FREE 



{filename|(l)} 



The FREE macro, used in conjunction with the 
KOLD=YES option of a DTFxx macro, frees a portion 
of a DASD device that is being held under DASD re- 
cord (track) protection. On a CKD device, that pro- 
tected portion is a track; on an FBA device, it is an 
integral number of contiguous FBA blocks. On an 
FBA device, the FREE macro is treated as a null oper- 
ation; all holding and freeing of fba block ranges is 
performed implicitly by Liocs. 

The same track (or blocks) can be held more than 
once without an intervening free if the hold re- 
quests are from the same task. The same number of 
FREES must be issued before the track (or block) is 
completely freed. However, a task is terminated if 
more than 16 hold requests are recorded without an 
intervening FREE, or if a FREE is issued to a file that 
does not have a hold request for that track (or 
block). For situations that require the use of the 
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FREE macro, refer to DOS/ VSE Macro User's 
Guide, as listed in the Preface. 

(filename 1(1)) : This operand is the same as the 
name specified in the DTP header entry. 

FREEVIS Macro 

Name Operation Operand 



[name] FREEVIS 



[ ADDRESS= (name 1 1 ( 1)} ] 
[,LENGTH= {name2|(0)} ] 
[,SVA=YES] 



The FREEVIS macro releases a block (or blocks) of 
virtual storage that was obtained by the GETVIS ma- 
cro. 

If you code the macro without any operand, 
DOS/VSE assumes that the start address of the block 
to be released is contained in register 1 and that the 
length of this block was placed into register 0. If the 
macro is issued without an operand, the macro must 
not contain a comment unless the comment begins 
with a comma. 

ADDRESS={namel|(l)}: The start address of 
the virtual storage block to be released in the GETVis 
area may be specified either in a 4-byte field ad- 
dressed by namel or in a register. 

LENGTH= (name2|(0)}: The length of the virtual 
storage block to be released may be specified in a 
4-byte field addressed by name2 or in a register. 
The length is specified in number of bytes. The 
smallest unit of virtual storage that can be released 
by FREEVIS is (a) 128 bytes if the GETVIS area is part 
of a partition or (b) 512 bytes if the GETVis area is 
part of the SVA. If the specified length is not a multi- 
ple of 128 or 512, respectively, it is rounded to the 
next higher integral multiple of 128 or 512. 

SVA=YES: SVA=yes can be specified only in a 
program that is executed with storage protection key 
zero. If SVA=YES is specified, DOS/vSE tries to fmd 
the block that is to be released in the SVA, otherwise 
in the pertinent partition. 

Return Codes in Register 15 

FREEVIS completed successfully 
4 The size ofthe partition GETVIS area is OK. 
8 The specified length is smaller than zero. 
12 The specified address is not within the GETVis 
area or the address is not (a) a multiple of 128 
bytes if the GETVis area is part of a partition, or 
(b) a multiple of 512 bytes if the GETVis area is 
in the SVA. 



16 The specified storage block to be released 
(ADDRESS+LENGTH) exceeds the GETVIS area. 

GENBTL Macro 



I»aind| GEHDTL 



|A0DII^ {iwiHeli{S,namel>Krl)] \ 

^KAMB«' {t»aiaeap,ji3me2>Kt2>}l 

iC0KTROt»^S}| 

[,LOCKOFT-{l|2}] 

tKEEP*^|YESy 

tOWNEH-* (TJ^SKj fARTitlOHl | 



The GENiSTL macro §«ierates a control block which 
is ^sed fey th^ LOCK/UNtocic macr<» to 
€il.queue/d«picue a r^ource access request The 
coatrol bioek, commonly calied "Vftv iP^tmt Tite 
Lock), Is generated at the time of program execu- 
tion. Space for tli« 0Tt is eitheir provided by the 
program, or it is to be acquired by DOS/vSE, 

ADD»« (iiaiiiet|(SyBaiitel>|<ri)}| specifies either 
the address or a register pointing to die address 
where the dtl is to be bull If thk operand is omit- 
ted, DOS/VSE re<|t»ests Mor^e to be alocated ta the 
partltiofi^s GETVIS area by an Implicit GETVIS re- 
quest Afler a successM getvcs, dos/vse places tbe 
DTUs address in register I . Register 15 contains the 
retttra code set by the impHcit OETVis reeL«est 

NAME^ {fiam€2|(S,iiai»e2)|<rl)} % specifies the 
addre^ or a register pointing to the address where 
as np to 12 byte long resource name is stored. It Is 
by tins name that DOS/vSE <xmtrols shared access of 
tbe resource as requested by acUve tasks via the 
LOCK macro. These tasks may all be active ^ one 
partition, or they may be distrlbttted over several 
paftidons; the resource-share control extends across 
partitions. 

lEHOIHss gOf VES}? If LENOTB-YBS iS speci- 
jOfed, the oiJ?i}DTL macro retams the length ofthe 
DTL la t^ter 0. With tEI^GTH«>JO, register S re- 
mains unchanged, 

GENL Macro 

Name Operatioa Operand 

[name] GENL phasenamel,phasename2, ... 

[ {,ADDRESS= {area|(S,area)|(r 1)} 

,LENGTH=number}] 

[ {,ADDRESS= {DYN|DYNAMIC 

[,ERREXIT= {addr|(S,addr)|(r2)} ]} ] 
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The GENL macro generates a local directory in the 
partition. It saves access time if you load the same 
phases more than once in the course of program 
execution. 

phasenamel,phasename2,...: Specify, for these 
parameters, the names of phases, for which entries 
in a local directory list are to be built. The list will 
be generated in alphameric sequence. You may 
specify up to 200 phase names. 

ADDRESS=specification,LENGTH=number: 

If the ADDRESS Operand is omitted, the assembler 
builds a 34-byte entry w^itnin tuc macro expansion 
for each of the specified phases and inserts the perti- 
nent phase name in the entry. The rest of the entry 
is filled in by the supervisor when the phase is called 
by a FETCH or load macro, with the list option for 
the first time. When, subsequently, the phase is 
called again, the entry is active. 

Coding address in conjunction with LENGTH 
indicates that the directory is to be built, during 
execution, at a location within your program whose 
address is given by the address operand. 

LENGTH gives the length of the field provided for 
the generation of the directory. If length is too 
short the assembler issues an mnote. 

ADDRESS=DYN,ERREXIT=specirication: 

Coding address=dynamic (a short form, 
ADDRESS=DYN, is allowed) directs the system to 
acquire, through a GETVIS, as much dynamic storage 
as needed. Note that in this case the contents of 
registers 0, 1, 14, and 15 will be over- written by exe- 
cution of the macro. 

ERREXIT is the address of a routine to be executed 
should the implicit GETVis fail. If the errexit ope- 
rand is omitted, an unsuccessful GETVis will cause 
the task to be canceled. 

GETIME Macro 

Name Operation Operand 



[name] GETIME 



[STANDARD|BINARY|TU] 
[,LOCAL|,GMT] 

(,MFG=(area|(S,area)|(r)}] 



The GETIME macro obtains the time-of-day at any 
time during program execution, provided the time of 
day option was specified at system generation. (If 
the time of day option was not specified at system 
generation, issuing GETIME only obtains zeros in- 
stead of a valid time.) 



STANDARD and LOCAL are assumed if no ope- 
rands are given. If the macro is issued without an 
operand, the macro must not contain a comment 
unless the comment begins with a comma. 

As long as no DATE job control statement is sup- 
plied, the calendar date and the system date in the 
communication region are updated every time 
GETIME is issued. Those dates are therefore accurate 
at any given moment. However, when the job 
stream contains a date job control statement, only 
the system date in the communication region is up- 
dated when GETIME is used; the calendar date is not 
changed in that case. 

If STANDARD is Specified, the time-of-day is re- 
turned in register 1 as a packed decimal number of 
the form hhmmss, where hh is hours, mm is minutes, 
and ss is seconds, with the sign in the low-order half- 
byte. The time-of-day may be stored and unpacked 
or edited. 

If BINARY is specified, the time-of-day is returned 
in register 1 as a binary integer in seconds. 

If TU is specified, the time-of-day is returned in 
register 1 as a binary integer in units of 1/300 sec- 
onds. 

LOCALjGMT: Specify local to obtain the local 
time or GMT if, in your program, you want to use 
Greenwich Mean Time. 

MFG=(area|(S,area)|(r)): The MFG operand is 
required if the program is to be reenterable and if 
option STANDARD applies (with options binary or 
TU, reentrancy is preserved in any case). It specifies 
the address of a 64-byte dynamic storage area, that 
is: storage which your program obtained through a 
GETVIS macro. This area is required for system use 
during execution of the macro. 

GETVIS Macro 

Name Operation Operand 



[name] GETVIS 



[ADDRESS= (name 1 1(1)}] 
[,LENGTH= (name2|(0)} ] 
[,PAGE=YES] 
[,POOL=YES] 
[,SVA=YES] 



The GETVIS macro retrieves a block of virtual stor- 
age from the GETVIS area of your partition or of the 
SVA. If you code the macro without any operand, 
dos/vse assumes that the length of the desired vir- 
tual storage area is contained in register and re- 
turns the start address of the area it retrieved for you 
in register 1 . If the macro is issued without an ope- 
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rand, the macro must not contain a comment unless 
the comment begins with a comma. 

ADDRESS={namel|(l)}: The start address of 
the requested virtual storage area is returned by the 
system either in the 4-byte field specified as a sym- 
bol by namel or in the specified register. (Register 
15 must not be used because it contains the return 
code.) The returned address is valid only if the re- 
turn code in register 15 is zero. If the operand is 
omitted, the address is returned in register 1 only. 

LENGTH= {name2|(0)} : The length of the re- 
quested storage block may be specified either in the 
4-byte field (specified as a symbol by name2) or in 
the specified register. The length is specified in 
number of bytes. The smallest unit that can be re- 
quested by GETVIS is (a) 128 bytes if the GETVIS area 
is part of a partition or (b) 5 12 bytes if the GETVIS 
area is part of the SVA. If the specified length is not 
a multiple of 128 or 512, respectively, it is rounded 
to the next higher multiple of 128 or 512. If the ope- 
rand is omitted, the system assumes that you have 
specified the length in register 0. 

PAGE=YES: If you want the requested storage 
area to start on a page boundary, specify page=yes. 
This may reduce the number of page faults. 

POOL=YES: If pool=yes is specified, getvis 
starts searching for the requested virtual storage area 
at the address specified in register 1 . In this case, it 
is your responsibiUty to provide a valid address in 
register 1. 

SVA=YES: sva=yes can be specified only in a 
program that is executed with storage protection key 
zero. If SVA=YES is specified, DOS/VSE retrieves the 
desired block of virtual storage from the SVA. Other- 
wise, DOS/VSE retrieves the block from the pertinent 
partition. 

Return Codes in Register 15 

GETVIS completed successfully. 
4 The size of the partition getvis area is OK. 
8 The specified length is negative. 
12 No more virtual storage is available in the 

GETVIS area. 
32 A hardware (storage) failure occured in the 
requested real partition getvis area. 

JDU MP Macro 

Name Operation Operand 

[name] JDUMP 



This macro provides a hexadecimal dump of the 
following: 

• The contents of either the entire supervisor area 
and the used part of the system GETVis area, or 
of some supervisor control blocks only (see 
Note below). 

• The contents of the partition that issued the 
macro. 

• The contents of the registers. 

Note: The dump includes the contents of some supervisor control 
blocks only, rather than the entire supervisor area, if the 
STDOPT job control command specifies DUMP=PART or NO, 
or if a job control statement //OPTION PARTDUMP or NO- 
DUMP is submitted. 

In addition, the macro causes the job to be termi- 
nated if JDUMP was issued by the main (or only) task 
of the program. If jdump was issued by a subtask, 
the macro causes that subtask to be detached with- 
out terminating the program in the partition. 

The dump provided by the macro is always di- 
rected to SYSLST; SYSLST, if disk or tape, must be 
opened; if SYSLST is a tape, that tape must be posi- 
tioned as desired. 

If JDUMP is issued by a job running in real mode, 
the storage contents of the partition are dumped 
only up to the limit as determined by the size par- 
ameter of the EXEC job control statement, plus the 
storage obtained dynamically through the GETVIS 
macro. If SIZE was not specified, the entire partition 
will be dumped. 

If JDUMP is issued by a program running in virtu- 
al mode, the entire partition is dumped. 

JOBCOMMacm 

N-gaae ^ ^^ ^ Operatiffltt ^ ^^ Oper^id 



\mm&\ lOBCOM 



FUNCT« (FUTCOMjGETCOM] , 

AREA={addr«ss|<fi», 

LENGTH=^engthKr2)| 



Tile JOBCOM macro aBows for commvmication be- 
twe^jji jobs or Job steps in a partition. Information 
being communicated is stored in a 256-byte area. 
DOS/VSE provides such am area for each partition. 
Through the jobCOM macro, a program either 
moves ittformation into that area or retrieves in- 
formation that had previously been stored there by 
another program. Th^ area remains unaltered from 
one job (or job step) to the next. Uxiless it is modi- 
fied through execution of the jobcom macro, the 
contents of the area remain unchanged over aiiy 
rtumber of jobs. 

Tlie program timt tssoses the JOBCOM macro must 
provide a register save area 18 luiiwords long. Prior 
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to execution of the macro, register 13 has to point to 
tliat save area. 



Note: If SYSLOG is assigned to a printer, the results of an FCB 
load operation initiated by an LFCB macro are unpredictable. 



rUNCTs={P1iTCOM|GETCOM) This operand 
describes the function that the macro is to perform. 
Specifying putcom causes information to be stored 
into the system-supplies area. The number of bytes 
to be moved is given by the length operand. If 
LENGTH yields a value suialtcr than 256, the remain- 
der of the area is left unaltered. 

Specifying getcom indicates that information is 
to be retrieved from the system-supplied area. 
Again, the number of bytes to be moved is given by 

AREA= {addressj(rl)) This operand gives the 
address of a field where the program provides 
(FUNcr-PUTCOM specified) or receives 
(FUNCT-GETCOM Specified) the information to be 
moved. 

LENGTH^ {Iei»gtiij(r2» This operand specifies 
the number of bytes to be moved. The value is ei- 
ther given as a self-defining term or in register nota- 
tion. If register notation is used, the specified regis- 
ter is expected to contain the length value. 

Length should be a positive number up to 256. If 
it is zero or negative, no information gets moved. If 
it is greater than 256, only 256 bytes are moved. 

LFCB Macro 

Name Operation Operand 



[name] LFCB 



SYSxxx,phasename 

[,NULMSG] 

[,FORMS=xxxx][,LPI=n] 



The macro can be used to load the forms control 
buffer (FCB) of a printer dynamically. That printer 
must not be an IBM 3800 Printing Subsystem; the 
macro is ignored on an IBM 3800. An FCB whose 
contents have been changed by means of this macro 
retains the changed contents until one of the follow- 
ing occurs: 

• another LFCB macro is issued for the printer; 

• an LFCB command is issued for the printer; 

• the SYSBUFLD program is executed to reload 
the printer's FCB; 

• IPL is performed for the system. 

The macro, when executed, generates messages to 
request operator action (such as changing forms), 
whenever manual action is required, and to inform 
the operator that the FCB of the specified printer has 
been reloaded. 



SYSxxx: The name of the logical unit associated 
with the printer whose FCB is to be loaded. 

You can specify one of the following: 

• SYSLST, 

• SYSLOG, or 

• a programmer logical unit (SYSnnn) assigned to 
a printer owned by the partition in which the 
program is being executed. 



phasename: The name by which the phase contain- 
ing the applicable FCB image is cataloged in the core 
image library. For information on the contents and 
format of an FCB image, see the section "System 
Buffer Load (SYSBUFLD)" in DOS/VSE System 
Control Statements. 

NULMSG: This operand specifies that the 80- 
character verification message, which is normally 
printed following the FCB load operation, is to be 
suppressed. This operand, if given, must be speci- 
fied immediately after phasename. 

If this operand is specified, the system continues 
normal processing immediately after the FCB load 
operation has been completed, and the operator 
cannot verify that the proper forms are placed on 
the printer. 

If the operand is omitted, the system prints the 
last 80 characters of the phase identified by phasen- 
ame, and causes an additional skip to channel 1 . 

FORMS=xxxx: This operand specifies the type of 
forms to be used on the printer whose FCB is being 
reloaded. For xxxx, a string of up to four alphamer- 
ic characters can be specified. The specified form 
number is included in a message to the operator. 

LPI=n: This operand, which should not be given 
for a PRTl -printer (with a device type code of PRTl), 
specifies the desired number of lines per inch. For n, 
you can specify either 6 or 8. 

If the macro is issued for a PRTl -printer and the 
specified spacing disagrees with the spacing code in 
the new buffer image, the system does not execute 
the FCB load operation and sets the appropriate re- 
turn code in register 15. 

If the macro is issued for a non-PRTl -printer, the 
system includes the operand in a message to the 
operator. 
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Return Codes in Register 15 

Successful completion of the fcb load operation is 
indicated to the problem program by a return code 
of 0. Note, however, that for an IBM 3800, register 

15 contains 0, although the macro was not executed. 
If the operation fails, register 15 contains one of the 
return codes listed below; in this case the FCB retains 
its original contents. The return codes are: 

Return Code Meaning 

Dec Hex 

4 X'04' The assigned printer is a PRT1 -printer, 

and the LPI operand specified in the ma- 
cro disagrees with the FCB image. 

8 X'08' No LUB is available for the specified 

logical unit. 

1 2 X'OC The specified logical unit has not been 

assigned or is currently unassigned. 

16 X'10' The specified logical unit is assigned to a 

device without an FCB. 

20 X'14' The printer assigned to the specified 

logical unit is down. 

24 X'18' The specified FCB image phase has not 

been found. 

28 X'1 C The specified FCB image phase is invalid 

for the printer assigned to the specified 
logical unit. 

By testing register 15, you can determine in your 
program whether or not the operation has failed. If 
the operation has failed, you can either terminate 
the job step or continue processing. Should you 
decide to continue processing, then the system by- 
passes the execution of the lfcb macro. 

LOAD Macro __^ 

Name Operation Operand 

[name] LOAD (phasename | (S,address) | ( 1 )) 

[,loadpoint| (S,loadpoint)| (0)] 
[,LIST= (listname|(S,listname)|(r 1)} ] 
[,SYS=YES] 
[,DE=YES] 
[,TXT=NO] 
[,MFG= (area|(S,area)|(r2)} ] 



The LOAD macro loads the phase specified in the 
first parameter from the core image hbrary (if this 
phase is not in the SVA) and returns control to the 
calling phase. After execution of the macro, the 
entry-point address of the called phase is returned to 
you in register 1 . For a non-relocatable phase, this 
address is the entry-point determined at link-edit 
time. For a relocatable phase, the entry point is ad- 
justed by the relocation factor. If the phase is in the 
SVA, it is not loaded; the entry point address in the 
SVA, however, is returned in register 1 . 

phasename|(S,address)|(l): For phasename speci- 
fy the name of the required phase. 



If DE=YES is not specified, the address as speci- 
fied in (S, address) or as loaded into a register points 
to an 8-byte field that contains the phase name. If 
DE=YES, the operand has a different meaning; refer 
to the discussion of the DE operand. 

Ioadpoint|(S,loadpoint)|(0): If loadpoint is pro- 
vided the load-point address specified to the linkage 
editor is overridden, and the phase is loaded at the 
specified address. The address used must be outside 
the supervisor area. When an overriding address is 
given, the entry-point address is relocated and re- 
turned in register 1 . An overriding loadpoint ad- 
dress must not be specified for a phase that had been 
linked as a member of an overlay structure. 

If the phase is non-relocatable, none of the other 
addresses in the phase are relocated; if the phase is 
relocatable, however, the entry point and address 
constants are updated with the relocation factor. 

If loadpoint is given in register notation, the reg- 
ister used must not be register 1. Preload the register 
with the loadpoint address. 

With (s,...) notation, the loadpoint address is de- 
rived from base register and displacement as assem- 
bled for loadpoint in the (S,loadpoint) specification. 

LIST={listnamel(S,listname)|(rl)}: For list- 
name specify the name of your local directory list 
generated in the partition by the genl macro. 
When this operand is included, the system scans the 
local directory list for the name of the required 
phase before it initiates a search for this phase name 
in the pertinent core image library directory. 

SYS=YES: If SYS=YES is specified, the system 
scans the system directory list (SDL) in the sva and 
the system core image library before the private core 
image library (if a private CIL is assigned at all). If 
nothing is specified, the private CIL takes prece- 
dence. 

DE=YES: This operand is useful if your program 
frequently loads one specific phase. DE=YES is in- 
valid if LIST is specified. 

DE=YES indicates that your program contains a 
34-byte field where you have placed a single directo- 
ry entry like those generated by the GENL macro. If 
this directory entry is active the directory scan 
mechanism is bypassed; if not, the entry will be 
filled in by the supervisor and then becomes active. 

If the first operand is written as phasename 
(instead of s-type or register notation) a directory 
entry will be generated within the macro expansion. 
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The generated directory entry will contain the pha- 
sename in the first 8 bytes. 

If you use (s,address) or register notation for the 
first operand you must set aside the 34-byte field 
yourself and point to it via this operand. The direc- 
tory entry must contain the phase name in the first 8 
bytes (left-justified and padded with blanks) and 
x'OB' at displacement X'OB'. 

TXT=NO: The specification TXT=NO (with 
LlST=listname or de=yes) is useful if a phase is 
loaded more than once in the course of your pro- 
gram. It causes a search for the directory entry with- 
out transfer of the contents (or text) of the phase 
itself and it indicates in the directory entry if and 
where the phase was found. This can be used to 
accomplish either of the following: 

1 . The directory entry can be filled in from the 
core image library for later FETCH/LOAD calls 
without the overhead of text transfer. 

2. You can establish whether a given phase is 
present in a core image library or the SVA since 
register contains the address of the directory 
entry and byte 16 of the directory entry appears 



as: 

X'06' 
X'12' 
X'OA' 



if the phase is not found 

if the phase is in the SVA 

if the phase is in the private CIL. 



Note: Test for these conditions by means of a Test Under Mask 
(TM) instruction, not a Compare instruction. 

MFG={area|(S,area)|(r2)}: The operand mfg is 
required if the program which issues the LOAD ma- 
cro is to be reenterable. It specifies the address of a 
64-byte dynamic storage area, that is, storage which 
your program obtained through a getvis macro. 
This area is required for system use during execu- 
tion of the macro. 

LOCK Macro 

• NaB» C^xBratiTO Operand ^^^^ 

fHam«J LOCK i[Ram«KS»niaine)J(r>^ 

t,rAlL^ (RETURKl WAlTCiWAmi 



The LOCK macro enqueues the task for accessing the 
named tesotirce. The resource must have been de- 
fined in the program by a dtl (Define The Lock) 
control block. A DTL is generated by issuing a DTL 
or geHDTL macro: it may be modified by issuing a 
MODDTL macro. 

{name[(S,name)|(r)} : specifies the dtl address, 

FAIL= {RETURNI WAITCIWAIT] : defines the 

5-14 DOS/VSE Macro Reference 



syMem action in case the resource <^imot1>e ob- 
tained: 

♦ FAIL^RBTUHN: causes the j^ystcm to return 
control back to the requesting program in any 
case. The requesting program has to oheck the 
return code in register 15 to fine out whellier or 
not the request was successful. 



jrjTT. 






WAIl C * causes i.«p »j^3t,«?m tu ptavjc lae 
requesting task in the wait state if the requested 
resource is found to be locked by another task. 
In all cases, control returns to the requesting 
program. The requesting program has to check 
the return code in register 1$ to ilne <mt wheth- 
er the request was successful, or whether an 
error occurred. 
• FAIL^ WAIT: requests the system to return 
control to the requesting task when the resource 
can be obtained. If the r«^ource is locked by 
another task^, the requesting task is set into the 
wait state until the resource is freed. In case of 
ati error condition (return codes 12, 16, 20), the 
requesting task is canceled. 

WAIT or WAITC cannot be specified if the resource 
is defined with OWMER-PARTtTlOR 

Return Codes in Register 15: 

Successful request: the resource is iocdced for 
the task (or for the partition if the resource is 
defined with partition ownership). 

4 Resource not available: the resource is already 
locked with a locking status that allows ao oon- 
current access. 

5 The lock table space is exhausted, 

12 The lock request is inconsistent with previous 
lock requests (by the same or other tasks). 

16 The request would have resulted ta a deacSock 
condittoiL 

20 DTL format error* 

Figure 5-3 presents a summary of system actioM 
by return codes, depending on the speciHcation of 
the FAIL operand. 

Figure 5-4 summarizes how DOS/VSE controls 
access to a resource* depending on the satisfactions 
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Fi^re 5-3. System actions by m\MXti code and FAIL operand. 
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request is granted (return code 0). 

request is inconsistent with current lock status (return code 1 2). 


W Access to 


the resource cannot be granted (return code 4 or 1 6). 





figure 5-4. SyMem action depending on control definition in D'I'Ls. 

of the CONTROL and i.oc:KOPT operands in the DFL 
or GENDTL macro. The illustration assumes that a 
task issues a lock request for a resource which is 
already locked. 

A task or partition may lock a resource more than 
once. DOS/VSt maintains a lock request count for 
the resource. 

When a resource is defined with LOCKOPT=l, a 
task may issue up to 255 LOCK requests with 
CONTROL=S. When a resource is defined with 
LOCKOPT=2, up to 255 LOCK requcsts with 
C0NTR0L=s and (if no other task locks the resource, 
exclusively) one lock request with CONTROL=L are 
allowed. 

When a resource is locked more than once by a 
task, this task has to issue at least as many unlock 
requests as it issued LOCK requests before it gives up 
the resource completely. If the resource is defined 
with 0WNF.R=PARTITI0N. the unlocking may be 
done by any task in the partition. 

MODDTL Macro 

Name Operation Operand 



Iname] MODDTL 



ADDR={naniel|(S,namel)j(rl)] 

[.NAML={nanie2i(S,name2);(r2)}] 

[.C0NTR0L={EiS}| 

l.LOCKOPT=lli2}] 

[,KEt-P={NO'YtS)| 

[.OWN t:R= {TASK'PARTITION} ] 

[.CHANGH={0N:0LT-11 



The MODDTL macro modifies operands (fields) of a 
DTL (Define The Lock) control block. A DTL is used 
by the lock/unlock macros to enqueue/dequeue 
a specific resource. The control block must have 
been generated by the DTL or giindtl macro. 

; I i '^0pfixaMs not speeifisM ii^the^MORDiri, itaero ■; U U 
^ kave tfie correspoiKdiag: JEMd itftl^ txtt iiai^ttged.; : 
O'lfe^^Jiii^.S^''^^ \y]|i|es iflt t^ MO!>DT^jinacmv i 



ADDR= (naiiicl!(S,nanic1)|(rl)}: specifies the 
address of the dil. 



NAME= (name2|(S,name2)|(r2)} : specifies the 
address or a register pointing to the address where 
an up to 12-byle long resource name is stored. It is 
by this name, that DOS/vsii controls shared access of 
the resource as requested by active tasks via the 
LOC K macro. These tasks may all be active in one 
partition, or they may be distributed over several 
partitions; the resource-share control extends across 
partitions. 



CHANGF= (ONIOFF) : cfl-\ngl=on sets up the 
DTL such that a subsequent unlock macro with 
namcl as operand would not release the resource, 
rather keep the resource locked, but reduce its lock- 
ing status. Reducing the lock status can be done 
only when the current lock status is defined with 
strongest possible values: CON rROL=t and 
LOCKOPT=L At least one of the operands c:ON IROL 
and LOCKOPT should be specified too. 
c.HANGi-:=OFF causes a subsequent unlock macro 
to resume its normal function: to dequeue the re- 
source. 

For a description of the other parameters refer to 
the DTL macro. 



MVCOM Macro 

Name Operation Operand 



[namel MVCOM 



lo.length, {fromHO)} 



The MVCOM macro modifies the content of bytes 12 
through 23 of the communication region of the par- 
tition from which the macro is issued. This area is 
commonly referred to as the user area. 
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The following example shows how to move three 
bytes from the symboUc location data into bytes 16 
through 18 of the communication region: 

MVCOM 16,3,DATA 

to: specifies the address (relative to the first byte of 
the region) of the first communication region byte 

t 1 ■ /- 1 



address constant 



length 



= Address of the first byte of the 
area to be paged in. 

= A binary constant indicating 
the length of the area to be 
paged in. 



A non-zero byte following an entry indicates the end 

nf the list 



length: represents the number of bytes (1 to 12) to 
be inserted. 

from|(0): represents the address (either as a symbol 
or in register notation) of the bytes to be inserted. 

PAGEIN Macro 

You can code the macro in either of the following 
two formats: 

Name Operation Operand 



[name] PAGEIN 



[name] PAGEIN 



beginaddr,endaddr 
[,begmaddr,endaddr] . . . 
[,ECB={ecbname|(0)}] 

{listname|(l)} 
[,ECB={ecbname|(0)}] 



The PAGEIN macro causes specific areas to be 
brought into real storage before their contents are 
needed by the requesting program. If the requested 
area is already in real storage the attached page 
frame will get low priority for the next page-outs. 
This function, however, does not include any fixing, 
so that it cannot determine whether all areas re- 
quested will still be in real storage when the entire 
request has been completed. 

On a system that was geaerated with vm- Y3ES (in 
the SUPVR geoeratioa macro), ex^ecutioti of the ma- 
cro results ia a uull ci|>eration. If the ecb operand Is 
specified^ die ECB will be po^d. 

beginaddr: Points to the first byte of the area to be 
paged in. 

endaddr: Points to the last byte of the area to be 
paged in. 

listname|(l): Is the name of a list of consecutive 
8-byte entries as shown below. 



xw 


address constant 


length minus i 







1 



where: 
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ECB=ecbname|(0): Specifies the name of the ecb, 
a fuUword defined by your program, which is to be 
posted when the operation is complete. An invalid 
ECB address causes the task to be canceled. 

Return Information 

The return information can be obtained from the 

ECB, byte 2. The meaning of these bits is shown 

below. 

Bit Meaning if bit is one: 

PAGEIN request is finished. 

1 The page table is full, the request cannot be queued 
at this time for further handling; the request is ig- 
nored, bit is set. 

2 One or more of the requested pages are outside the 
requesting program's partition; PAGEIN is not per- 
formed for these pages. 

3 At least one negative length has been detected in the 
area specifications; PAGEIN is not performed for 
these areas. 

4 List of areas that are to be paged in is not completely 
in the requesting program's partition; the request is 
ignored, bit is set. 

5 Paging activity is too high in the system, no perfor- 
mance improvement is possible. 

6-7 Reserved 

Any combination of the return bits in the ECB is 
possible. 

Use the wait macro with the ecbname as operand 
for completion of the PAGEIN macro, before the bits 
in byte 2 of the ECB are tested. 

PDUMP Macro 

Name Operation Operand 



[name] PDUMP 



{address l|(rl)} , {address2|(r2)} 
[,MFG= {area|(S,area)|(r3)}] 



This macro provides a hexadecimal dump of the 
general registers and of the virtual storage area con- 
tained between the two address expressions 
(address 1 and address2). The contents of registers 
and 1 are over-written, but the CPU status is re- 
tained. Thus, PDUMP furnishes a dynamic dump 
(snapshot) useful for program checkout. Processing 
continues with your next instruction. 



The dump is always directed to SYSLST with 121- 
byte records. The first byte is an ASA control charac- 
ter. When SYSLST is a disk drive, you must issue an 
OPEN or OPENR macro to any DTP assigned to 
SYSLST after each pdump that is executed. The 
OPEN or OPENR macro updates the disk address 
maintained in the dtp table to agree with the ad- 
dress where the PDUMP output ends. If the OPEN or 
OPENR is not issued, the address is not updated, and 
the program is canceled when the next PUT is issued. 

If non-addressable areas were included in the 
range of PDUMP, a message wiU be printed to indi- 
cate this. 

(addressl|(rl)},(address2|(r2)}: One or both of 
the addresses can be specified in register notation. If 
address2 is not greater than address 1, or address 1 is 
greater than the highest address in the allocated 
virtual storage, the macro results in no operation. If 
the value in address2 is greater than the end of the 
allocated virtual storage area, the virtual storage 
between address 1 and the end of the allocated virtu- 
al storage is dumped. 

MFG= (area|(S,area)|(r3)} : The mfg operand is 
required if the program which issues the PDUMP is to 
be reenterable. It specifies the address of a 64-byte 
dynamic storage area, that is, storage which you 
obtained by GETVIS macro; this area is needed by 
the system during execution of the macro. 

PFIX Macro 

You can code the macro in either of the following 
two formats: 

Name Operation Operand 



[name] PFDC 
[name] PFIX 



beginaddr,endaddr 
[,beginaddr,endaddr] . 

{listname|(l)} 



The PFIX macro causes specific pages to be brought 
into real storage and fixed in their page frames until 
they are released at some later time. The maximum 
number of pages that may be fixed at any one time 
is specified via the allocr command. Each time a 
page is fixed a counter for that page is incremented. 
This counter may never exceed 255 for any page. 

If your supemsor was geiierated with vm^yes (in 
the SUPVR generation macro), execution of the ma- 
cro results in a null operation; the retam code is set 
to zero. 



beginaddr: Points to the first byte of the area to be 
fixed. 

endaddr: Points to the last byte of the area to be 
fixed. 

listname|(l): Is the name of a list of consecutive 
8-byte entries as shown below. 



X'OO' 


address constant 


length minus 1 







1 



where: 

address constant 

length 



Address of the first byte of 
the area to be fixed. 

A binary constant indicat- 
ing the length of the area to 
be fixed. 



A non-zero byte following an entry indicates the 
end of the list. Register notation may be used. 

Exceptional Conditions 

If a PFIX causes the count of fixes for a page to ex- 
ceed 255, the task issuing the PFix is canceled. 

If it is not possible to fix all pages requested, 
then none will be fixed. 

If PFIX is issued in a program running in real 
mode, it is ignored and register 15 contains 0. 

Return codes in Register 15 

if the pages were successfully fixed. 

4 if the number of pages to be fixed for one re- 
quest exceeds the number of PFlxable page 
frames; in order for this PFix request to be satis- 
fied, more PFlxable storage must be allocated 
through the allocr command. 

8 if not enough page frames are available in the 
partition because of previous PFlxes or current 
system resource usage; this pfix request could, 
however, be satisfied at another time without 
reallocating PFixable storage. 
12 if one of the specified addresses was invalid. 

PFREE Macro 

You can code the macro in either of the following 
two formats: 

Name Operation Operand 



[name] PFREE 
[name] PFREE 



beginaddr,endaddr 
[, beginaddr,endaddr] . . . 

{listname|(I)} 
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Each page in the virtual address area is assigned a 
'PFix counter'. If a page is not fixed - that is, if it is 
subject to normal page management - the counter is 
0. Whenever a page is fixed by using a PFlx macro 
its counter is increased by one. All pages whose 
counters are greater than remain fixed in real stor- 
age. 

The PFREE macro decrements the counter of a 
specified page by 1 . If a PFREE is issued for a page 
whose counter is 0, that PFREE is ignored since the 
page has already been freed. 

If your supervisor was generated with VM=YES (in 
the SUPVR generation macro), execution of the ma- 
cro results in a null operation; the return code is set 
to zero. 

beginaddr: Points to the first byte of the area to be 
freed. 

endaddr: Points to the last byte of the area to be 
freed. 

Iistname|(l): Is the symbolic name of a list of con- 
secutive 8-byte entries as shown below. 



X'OO' 


address constant 


length minus 1 







1 



issued to an ECB removes a task waiting for the ECB 
from the wait state. 

e€bname|(l): Provides the address of the ECB that 
is to be posted. 

SAVE= {savearea|(0)) : This operand may be 
used for taking a specific waiting subtask out of the 
wait state. The operand causes DOS/VSE to locate 
the save area whose address is specified in the ope- 
rand and to take only the subtask associated with 
this save area out of the wait state. This task nor- 
mally is waiting for the specified ECB to be posted. 

Although time is saved by specifying this ope- 
rand, other tasks waiting for this ECB are not taken 
out of the wait state for this event by this issuance of 
the POST macro. This does not guarantee that they 
will stay in the wait state until another POST is is- 
sued. On the contrary, other events could cause the 
other tasks to be dispatched. For this reason the 
POST macro should not be used with the save ope- 
rand to control subtask operation unless separate 
ECB's are used. Otherwise, it should be used only to 
save time. When a post is issued without the save 
operand, all tasks waiting for the ECB are taken out 
of the wait state, and the highest priority task re- 
gains control. 



where: 

address constant 

length 



RCB Macro 



Address of the first byte of 
the area to be fixed. 

A binary constant indicat- 
ing the length of the area to 
be fixed. 



A non-zero byte following an entry indicates the 
end of the list. 

Exceptional Conditions 

If PFREE is issued by a program running in real 
mode, the macro is ignored. 

Return codes in Register 15 

if the pages were successfully freed. 
12 if one of the addresses specified was invalid. 

POST Macro 

Name Operation Operand 



[name] POST 



{ecbname|(l)} 

[,SAVE=(savearea|(0)}] 



This macro provides intertask communication by 
posting an ECB (it turns on byte 2, bit 0). A post 



Name Operation Operand 



[name] RCB 



The RCB macro generates an 8-byte word-aligned 
resource control block (RCB); this block allows you 
to protect a user-defined resource if the ENQ macro 
is issued before (and the DEQ macro is issued after) 
each use of the resource. The format of the RCB and 
its use is shown below. 

Bytes Purpose of bits 

All bits are set to 1 to indicate that the resource 
has been placed in a priority queue by the ENQ 
macro. 

1 -3 Reserved 

4 If bit = 1 : Another task is waiting to use the 

resource. 
Bits 1-7: Reserved. 

5-7 ECB address of current resource owner. 



RE A LAD Macro 



Name Operation Operand 



[name] REALAD {address|(l)) 
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In s/370 mode, the realad macro returns the real 
address corresponding to a specified virtual address. 
If issued in ecps.vse mode, the macro returns the 
specified virtual address. 

address|(l): Is the virtual address to be converted. 
It can be specified as a symbol or in register nota- 
tion. 

Register returns the address corresponding to 

the specified virtual address if and only if the virtual 

address points to a PFixed page, otherwise register 

contains 0. Thus, the macro can be used to test if a 
page is PFlxed. 

Note: The pages of a partition running in real mode are treated 
as if they were fixed. 

RELEASE Macro 

Name Operation Operand 



[name] RELEASE 



(SYSnnn[,SYSnnn]...) 
[,savearea] 



RELEASE specifies the names of programmer logical 
units to be released, release may be used only for 
units used within a given partition . 

The operand SYSnnn specifies the programmer 
logical unit that is to be released. Up to 16 units 
may be specified in a list, which must be encloseu ... 
parentheses. 

All the units specified are checked by the assem- 
bler to assure that no system logical units are re- 
quested for release. If system logical units are speci- 
fied, an MNOTE is issued and such units are ignored. 
Before any release is attempted, a check is made for 
ownership of the unit. If the requesting partition 
does not own the unit, or if the unit is already un- 
assigned, the request is ignored. 



RELPAG Macro 

You can code the macro in either of the following 
two formats: 

Name Operation Operand 



[name] RELPAG 
[name] RELPAG 



beginaddr,endaddr 
[,beginaddr,endaddr] . . . 

(listname|(l)} 



The RELPAG macro causes the contents of one or 
more storage areas to be released. If the affected 
areas are in real storage when the RELPAG macro is 
executed, their contents are not saved but are over- 
written when the associated page frames are needed 
to satisfy pending page frame requests. 

After the RELPAG macro has been executed for an 
area and a location in that area is referenced again 
during the current program execution, the related 
page is attached to a page frame which contains all 
zeros. 

The storage area is released only if it contains at 
least one full page. You can be sure of this only if 
the specified area is 4K minus 1 byte, or bigger (see 
Figure 5-5). 



2k 



2k 



1 — First byte of page n 

Starting address of specified 
1 area (lengtii = 4k-2 bytes) 








Page n 






Page n + 1 








'I 

End address of specified area ' 

Last byte of page n + 1 



savearea: Is the name of an 8-byte word-aligned 
area where registers and 1 are saved for your pro- 
gram. If the operand is not provided, the contents of 
registers and 1 are over- written. 

The macro expansion includes a unit table and 
loads the table's address into register 0. If the sa- 
vearea operand is specified, the macro expansion 
saves registers and 1 . 

If there is no permanent assignment, the device is 
unassigned. If the device is at permanent assign- 
ment level, no action is taken on the unit. 

Recommendation: You should inform the system 
operator via a message that the assignment was re- 
leased. 



Figure 5-5. Worst case of an area not containing one full page. 

beginaddr: Points to the first byte of the area to be 
released. 

endaddr: Points to the last byte of the area to be 
released. 

listname|(l): Is the symbolic name of a list of con- 
secutive 8-byte entries as shown below. 



X'OO' 


address constant 


length minus 1 



1 

where: 
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address constant = Address of the first byte of the 
area to be released. 

length = A binary constant indicating 

the length of the area to be re- 
leased. 

A non-zero byte following an entry indicates the end 
of the list. 

Register notation may be used. 

Exceptional Conditions 

• The program is running in real mode. 

• The area is, fully or partially, outside of the 
virtual partition of the requesting program. 

• A page handling request is pending for the ref- 
erenced page(s). 

• The page(s) is (are) fixed. For these pages, the 
RELPAG request will be ignored. 

• The supervisor was not generated with 
PAGEIN=n in the SUPVR macro (in this case the 
program will be canceled). 

Return Codes in Register 15 

All referenced pages have been released or the 
request has been ignored because the request- 
ing program is running in real mode. 

2 The begin address is greater than the end ad- 
dress, or a negative length has been found. 

4 The area, fully or partially, does not belong to 
the partition where the issuing program is run- 
ning. The release request has only been execut- 
ed for those pages which belong to the partition 
of the issuing program. 

8 a. At least one of the requested pages is tempo- 
rarily fixed (via ccw-translation) and/or 
PFixed. The release request has only been exe- 
cuted for the unfixed pages, 
b. A page handling request (page fault, tempo- 
rary fix, PFix) for at least one of the requested 
pages is pending (caused by asynchronous 
processing within a partition). The release re- 
quest has not been executed for those pages 
which are involved in a page handling request. 
16 List of areas that are to be released is not com- 
pletely in the requesting program's partition. 
The request is ignored. 

Any combination of the return codes 2, 4, and 8 is 
possible. 

RETURN Macro 

Name Operation Operand 

[name] RETURN (rl[,r2]) 



The RETURN macro restores the registers whose 
contents were saved and returns control to the call- 
ing program. 

The operands rl,r2 specify the range of the regis- 
ters to be reloaded from the save area of the pro- 
gram that receives control. The operands are written 
as self-defining values. When inserted in an LM 



registers in the range from 14 through 12 (14, 15, 
through 12) to be restored from words 4 through 18 
of the save area. If r2 is omitted, only the register 
specified by rl is restored. To access this save area, 
register 13 must contain the save area address. 
Therefore, the address of the save area should be 
loaded into register 13 before execution of the 
RETURN macro. 

RUNMODE Macro 

Name Operation Operand 

[name] RUNMODE 



The RUNMODE macro returns the following inform- 
ation to the program issuing it: 

• Register 1 contains if the issuing program is 
running in virtual mode. 

• Register 1 contains 4 if the issuing program is 
running in real mode. 

No operand is required for this macro. 



SAVE Macro 



Name Operation Operand 



[name] SAVE 



(rl[,r2]) 



The SAVE macro stores the contents of specified 
registers in the save area provided by the calling 
program. 

The operands rl,r2 specify the range of the regis- 
ters to be stored in the save area of the calling pro- 
gram. The address of this area is passed to the pro- 
gram in register 13. The operands are written as 
self-defining values so that they cause desired regis- 
ters in the range of 14 through 12(14, 15, through 
12) to be stored when inserted in an STM assembler 
instruction. 

Registers 14 and 15, if specified, are saved in 
words 4 and 5 of the save area. Registers through 
12 are saved in words 6 through 18 of the save area. 
The contents of a given register are always stored in 
a particular word in the save area. For example, 
register 3 is always saved in word 9 even if register 2 
is not saved. 
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If r2 is omitted, only the register specified by rl is 
saved. 

SETIME Macro 

Name Operation Operand 



SETPFA Macro 



Name Operation Operand 



[name] SETIME 



{timervalue|( 1)} ,[tecbname|(r)][,PREC] 



The SETIME macro sets the interval timer to the 
specified value. 

timervalue|(l): The amount of time for the inter- 
val. This value can be specified either as an abso- 
lute expression or in register notation. If register 
notation is used, the pertinent register must contain 
the time value. 

The largest allowable value is 55,924 seconds — 
equivalent to 15 hours, 32 minutes, 4 seconds — if 
PREC is omitted, and 8,388,607 — equivalent to 7 
hours, 46 minutes, 2 seconds (approximately) — if 
PREC is specified. The positional operand PREC indi- 
cates that the timer value is expressed in units of 
1/300 of a second. When PREC is omitted, the timer 
value is in seconds. 

tecbname|(r): Specifies the name (address if regis- 
ter notation is used) of a timer event control block 
(TECB) which must have been defined previously in 
your program by a TECB macro. If you use register 
notation, register and 1 must not be used. After 
having executed the SETIME macro, the system re- 
turns the TECB address in register 1. 

When a program is restarted from a checkpoint, 
any timer interval set by a SETIME macro is not res- 
tarted. 

The SETIME macro must not be used within an 
abnormal termination exit routine. 

The setting of a time interval can be utilized in 
one of two ways. In the first method, the program 
sets up linkage to an interval timer exit routine by 
issuing the stxit it macro. When the time interval 
specified in SETIME elapses, control is given to that 
routine (if a routine is not supplied to the supervisor 
by the time of the interruption, the mterruption is 
ignored). When using SETIME in this way, the 
tecbname operand must not be specified. 

In the second method, specifying the tecbname 
operand causes a TECB to be posted when the time 
interval has elapsed: bit of byte 2 in the TECB is set 
to 1 . This event bit is set to when SETIME is issued. 
A task may be waiting for the TECB to be posted by 
having issued the wait or waitm macro. 



[name] SETPFA 



(entryaddressl(O)) 



The SETPFA macro either establishes or terminates 
linkage to a page fault appendage routine that is to 
be entered each time a page fault occurs or is com- 
pleted. You will find more information on how to 
write such a routine in Appendix F of the DOS/VSE 
Macro User's Guide, as listed in the Preface. 

If your supervisor was generated with VM=^YES (in 
tlie SUFVR geinfjratiojt macro), executiOB of the ma- 
cro results in a naS operation, 

entry address 1(0): If an entry address is specified, 
execution of the macro establishes linkage to the 
appendage routine. The routine at that address will 
be entered every time a page fault in the associated 
task occurs or is satisfied. The routine to be entered 
and aU areas referenced by the routine must be fixed 
in real storage using the PFIX macro before setpfa 
is issued. The entry address may be specified as a 
symbol or in register notation. 

If SETPFA is issued without an operand, the link- 
age to the page fault appendage is terminated. Each 
issuance of SETPFA supersedes all previous setpfa's 
for that task. 

A page fault appendage is called only when a 
page fault occurs in the task owning the appendage. 
If a page fault occurs while a supervisor service rou- 
tine is working for the owning task, the appendage is 
not called. The same may apply to an IBM-supplied 
component such asACF/VTAME. 

SETT Macro 

« 

Name Operation Operand 



[name] SETT 



(timervalue|(l)} 



The SETT macro sets the task timer to the value, in 
milliseconds, specified in the operand. The largest 
allowable value is 21474836 milliseconds. A register 
can be specified, and if it is, that register must con- 
tain the number of milliseconds in binary. You can 
use the SETT macro only if your supervisor was gen- 
erated with TTlME=partition-iD specified in the 
FOPT generation macro. 

The SETT macro can be issued only by the main 
task of the partition owning the task timer. If it is 
issued by a program running in a partition not own- 
ing the task timer, the program is canceled and an 
error message indicating illegal SVC is printed. 



Chapter 5: System Control Macros 



5-21 



SETT must not be used within an abnormal termi- 
nation exit routine. 

The time interval is decremented only while the 
task is executing. When the specified time interval 
has elapsed, the task timer routine supplied in the 
STXIT TT macro is entered. 

If a routine is not supplied to the supervisor by 



thp timft ctfthe. iv.it 



ruption, txxC intcri upt is ignoreu. 



When a program is restarted from a checkpoint, 
timer intervals set by a SETT macro are not restarted. 

STXIT Macro 



To establish linkage: 
[name] STXIT 



{AB|IT|PC|OC|TT) 

, {rtnaddr|(0)} , {savearea|(l)) 

[,OPTION= (DUMP INODUMP) ] 



To terminate linkage: 

[name] STXIT {AB|IT|PC|OC|TT} 

The STXIT (set exit) macro estabhshes or terminates 
linkage from the supervisor to an exit routine of 
your program for handling the specified condition. 
Linkage must be established before an interrupt 
occurs. Use the EXIT macro to return from these 
routines. 

When restarting a program from a checkpoint, 
any STXIT linkages established prior to the check- 
point are destroyed. 

If, in an exit routine, you are issuing I/O 
request(s) requiring the same logic module as your 
main routine, you must generate a read-only module 
by specifying rdonly=yes in the DTP and in the 
logic module. Both the main routine and the exit 
routine require a save area of their own. Detailed 
information on the save area and interrupt status is 
given in DOS/ VSE Serviceability Aids and Debug- 
ging Procedures. 

AB: An abnormal task termination routine is en- 
tered if a job or task is terminated for some reason 
other than a cancel, DETACH, dump, or eoj macro 
being issued by the task itself. Upon entry to the 
task's abnormal termination routine, 

• termination messages and a partition dump are 
produced, depending on selected options (see 
the OPTION operand below). 

• bit 1 of byte 2 in the task's attachment ECB is 
posted (if an ECB was specified in the attach 
macro). 

• register contains the abnormal termination 
code in its low order byte (see Figure 5-6). 



• register 1 points to the task's abnormal- 
termination save area, which contains the inter- 
rupt status information and the contents of reg- 
isters through 15 at the time of abnormal ter- 
mination. 

The abnormal termination routine can then ex- 
amine this data and take whatever action is neces- 

Macros which might be used in this routine are, 
for instance, POST and CLOSE. However, if an ab- 
normal termination condition occurs within an ab- 
normal termination routine, the job or task is abnor- 
mally terminated without regard to an abnormal 
termination exit. Thus, your program's abnormal 
termination routine should avoid macros such as 
ENQ, CHKPT, and any I/O macros which may cause 
an abnormal termination. 

After the appropriate action is taken, your abnor- 
mal termination routine should end with a CANCEL, 
DETACH, DUMP, or EOJ macro. 

If your routine issues the DUMP macro, the system 
produces a storage map of the partition even if job 
control option NODUMP was specified. For the parti- 
tion, SYSLST may be assigned to a 321 1 printer. If, in 
addition, indexing was used before your abnormal 
termination routine received control, a certain num- 
ber of characters on every line of the printed dump 
may be lost, unless you reload the printer's FCB 
(forms control buffer) by issuing an LFCB macro 
before you issue the dump macro. The FCB image 
to be loaded in this case must not have an indexing 
byte. 

If the CANCEL macro is issued in the main task, 
the entire partition is terminated with every subtask 
abnormal termination exit taken in order of priority. 

If the system was generated with the multitasking 
option, each task may require its own abnormal 
termination routine. A main task can attach a sub- 
task with an absave operand. This assumes the 
subtask will use the main task's abnormal termina- 
tion routine. However, the subtask may override 
this specification by issuing its own STXIT AB macro. 

If an abnormal termination condition occurs and 
linkage has not been established to an abnormal 
termination routine, processing in the partition is 
abnormally terminated. However, if the abnormal 
termination condition occurs in a subtask without 
exit linkage, only the subtask is terminated. 

When subtasks are detached or canceled, associ- 
ated time intervals and exit linkages are cleared. 

IT: An interval timer interruption routine is entered 
when the specified interval elapses. If the program 
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Hexadecimal 
representation 


Specific abnormal termination code meaning 


00 


Default value for all cases other than those listed below 


OF 


Invalid FBA DASD address for SYSFIL 


10 


Normal EOJ 


11 


No channel program translation for unsupported device 


12 


Insufficient buffer space for channel program translation 


13 


CCW with count greater than 32K 


14 


Page pool too small 


15 


Page fault in disabled program (not a supervisor routine) 


16 


Page fault in MICR stacker select or page fault appendage routine 


17 


Main task issued a CANCEL macro with subtask still attached 


18 


Main task issued a DUMP macro with subtask still attached 


19 


Operator replied cancel as the result of an I/O error message 


1A 


An I/O error has occurred (see interrupt status information) 


1B 


Channel failure 


1C 


CANCEL ALL macro issued in another task 


1D 


Main task terminated with subtask still attached 


IE 


A DEQ macro was issued for a resource but tasks previously requesting a resource cannot be found 
because their save areas (containing register 0) were modified 


IF 


CPU failure 


20 


A program check occurred 


21 


An invalid SVC was issued by the problem program or macro 


22 


Phase not found in the core image library 


23 


CANCEL macro issued 


24 


Canceled due to an operator request 


25 


Invalid virtual storage address given (outside partition) 


26 


SYSxxx not assigned (unassigned LUB code) 


27 


Undefined logical unit 


28 


Reserved 


29 


Reserved 


2A 


I/O error on page data set 


2B 


I/O error during fetch from private core image library 


2C 


Page fault appendage routine passed illegal parameter to supervisor 


2D 


Program cannot be executed /restarted due to a failing storage block 


2E 


Invalid resource request (possible deadlock) 


2F 


More than 255 PFIX requests for one page 


30 


Read past a /& statement 


31 


I/O error queue overflow during system error recovery procedure 


32 


Invalid DASD address 


33 


No long seek on a DASD 


35 


Job control open failure 


36 


Page fault in I/O appendage routine 


38 


Wrong privately translated CCW 


39 


Reserved 


40 


ACF/VTAME error, invalid condition 


41 


ACF/VTAME error, invalid condition 


42 


Invalid extent information violates DASD file protection 


FF 


Unrecognized cancel code 



Figure 5-6. Abnormal termination codes. 
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issuing the STXIT macro instruction is a acf/vtame 
application program, the interruption exit will not 
be taken while acf/vtame is processing any request 
on behalf of the application program. The exit will 
be taken when acf/vtame has completed the 
program's request. 

An interval timer interruption is ignored if no exit 
linka'^e has been established. 



If an interval timer interrupt occurs while an in- 
terval timer exit routine is still processing, the han- 
dling of the interrupt is delayed. When processing 
ends with exit it, the it exit routine is entered again 
to nrocess the new IT interrupt. TThis can only oc= 
cur if a short time interval was issued in your exit 
routine). 

OC: An operator communication interruption rou- 
tine is entered when you press the request key on the 
console and type the MSG command. In case of mul- 
titasking, only the main task can process this condi- 
tion. 

An operator communication interruption is ig- 
nored if no exit linkage has been estabUshed. 

PC: A program check interruption routine is en- 
tered when a program check occurs. If a program 
check occurs in a routine being executed from the 
logical transient area, the job containing the routine 
is abnormally terminated. 

A program check interruption routine can be 
shared by more than one task within a partition. To 
accompUsh this, issue the STXiT macro in each sub- 
task with the same routine address but with separate 
save areas. To successfully share the same PC rou- 
tine, the routine must be reenterable, that is, it must 
be capable of being used concurrently by two or 
more tasks. (The specified exit is not taken if the 
program check occurs while acf/vtame is process- 
ing a request issued by the program.) 

If a program check condition occurs in a main 
task without exit linkage, processing in the partition 
is terminated. However, if this same condition oc- 
curs in a subtask, only the subtask is terminated. 

TT: Linkage to a task timer interruption routine 
can be established only if TTlME=partition-lD was 
specified in the fopt macro for supervisor assembly. 

A task timer interruption routine is entered when 
the time interval specified in the sett macro has 
elapsed. The STxiT (and exit) tt macro can be 
issued only by the main task of the partition owning 
the task timer. If it is issued by a program running 
in a partition not owning the task timer, the program 



is canceled and an error message indicating illegal 
SVC is printed. 

A task timer interruption is ignored if no exit 
linkage has been established. A task timer interrupt 
is ignored if it occurs while a task timer exit routine 
is still processing. (This can happen only if a short 
time interval was issued in your exit routine). 

rtnaddr: Entry point address of the routine that 
processes the condition described in the first ope- 
rand. Your exit routine may be located anywhere in 
the program. 

savearea: Address of a 72-byte area in which the 
supervisor stores the old interrupt status information 
and general registers through 15, in that order. 
Your program must have a separate save area for 
each routine that is included. 

OPTION= (DUMP INODUMP) ; This operand 
can be used only when setting up linkage (STXiT ab) 
to an abnormal termination exit routine. It deter- 
mines whether termination messages and a dump 
will be issued upon entry to the routine. 

If the option operand is omitted or if 
OPTlON=DUMP is specified, termination messages 
are issued upon enry to the abnormal termination 
routine. In addition, a partition dump is produced 
unless the job control option NODUMP is active. 

If OPTlON=NODUMP is Specified, neither a termi- 
nation message nor a dump is produced. However, 
if the abnormal termination routine terminates ab- 
normally, termination messages and the dump are 
given regardless of the OPTION specification in the 
STXIT macro. 

If your routine ends with a DUMP macro and the 
STXIT macro was specified without 
OPTlON=NODUMP, you will obtain two dumps. 

Figure 5-7 shows what happens when one of the 
five conditions occurs while an STXIT routine is be- 
ing processed within a particular partition. 

TEC B Macro 

Name Operatioa Operand 

[name] TECB 



The TECB macro generates a timer event control 
block which can be referred to by the symbol you 
specify in the name field. This block contains an 
event bit that indicates when the time interval speci- 
fied in SETIME has elapsed. The format of this block 
is as follows: 
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Byte 


Purpose of bits 




0-1 


Reserved 






2 


0: If = 


time specified in 
elapsed. 


SETIME has not 




If 1 = 


time specified in 
elapsed. 


SETIME has 




1-7: Reserved 




3 


Reserved 






TESTT Macro 






Name 


Operation 


Operand 




[name] 


TESTT 


[CANCEL] 





The TESTT macro can be used only if 
TTlME=partition ID was specified in the FOPT gener- 
ation macro for supervisor assembly. 

The TESTT macro is used to test the amount of 
time that has elapsed from a task timer interval set 
by an associated SETT. The TESTT macro returns the 
time remaining in the interval, expressed in hun- 
dredths of milliseconds in binary, in register 0. 

If CANCEL is specified, the remaining time of the 
interval is canceled, and the task timer exit routine is 



Routine being 
Processed 


Condition Occurring 


AB 


IT 


00 


PC 


TT 


AB 


C 


D 


1 





D 


IT 


S 


E 


H 


H 


H 


00 


S 


H 


1 


H 


H 


PC 


S 


H 


H 


T 


H 


IT 


S 


H 


H 


H 


1 



C Job canceled immediately without entering AB routine 
again. 

D Interrupt is delayed and the TT or IT exit routine is en- 
tered after the EXIT AB macro is issued. If no EXIT AB is 
issued, the interrupt is ignored. 

E Handling of new timer interrupt delayed until execution 
of EXIT IT for original interrupt. 

H Condition honored. When processing of new routine 
completes, control returns to interrupted routine. 

I Condition ignored. 

S Execution of the routine being processed is suspended, 
and control transfers to the AB routine. 

T Job abnormally terminated. If AB routine is present, its 
exit is taken. Otherwise, a system abnormal termination 
occurs. 

Notes: 

1 . If an operator communication interruption routine or a 
program check interruption routine is in process when a 
timer interrupt occurs, your timer routine will be processed; 
when it completes, control returns to interrupted routine. 

2. If a task is using a logical transient routine when a timer 
interrupt occurs, your timer routine is not entered until the 
logical transient routine is released. 

Figure 5-7. Effect of an AB, IT, OC, PC, or TT interrupt while 
an STXIT routine is being executed. 



not entered. If the macro is issued without an ope- 
rand, the macro must not contain a comment unless 
the comment begins with a comma. 

The TESTT macro can be issued only by the main 
task of the partition owning the task timer. If it is 
issued by a program running in a partition not own- 
ing the task timer, the program is canceled and an 
error message indicating illegal SVC is printed. 

T PIN Macro 

Name Operation Operand 

[name] TPIN 



The TPIN macro is available primarily for the tele- 
communication appUcations that require immediate 
system response. The macro causes one or more 
partitions (other than the one issuing the macro) to 
be deactivated. The number of partitions that can 
be deactivated is specified in the tpbal command. 
The partitions to be deactivated are the ones with 
the lowest priorities. This request is ignored in each 
of the following cases: 

• The operator has not made tp balancing active 
by means of the tpbal command. 

• None of the partitions specified in the tpbal 
command contains a program running in virtu- 
al mode. 

• The only partition that could be affected by tp 
balancing is the partition that issued the tpin 
request. 

• There is no paging in the system. 

The TPIN macro must always be used in conjunc- 
tion with the TPOUT macro. The operand field is 
ignored. 

H'yDur supervisor was generated with vM-Y^ <m 
the SWVR generation macro)* execution of the m.a- 
CFO rei^lts ia a atili operatioa. 

TPOUT Macro 

Name Operation Operand 

[name] TPOUT 



The TPOUT macro causes DOS/VSE to reactivate par- 
titions that had been deactivated by the TPIN macro. 

Failure to issue the tpout macro can cause con- 
siderable and unnecessary performance degradation 
in the batch partition(s). The operand field is ig- 
nored. 

If your supervisor was generated with vm=yes (in 
the SUPVR generation macro), execution of the ma- 
cro results in a null operation. 
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TTIMER Macro 



Name Operation Operand 



[name] TTIMER [CANCEL] 



The TTIMER macro is used to test how much time 
has elapsed of an interval which was set in the same 
task by the associated setime macro. The ttimer 
macro returns the time remaining of the interval, 
expressed in hundredths of seconds in binary, in 
register 0. 

If CANCEL is specified, the time interval set in 
that task is canceled. As a resuU of the ttimer 
CANCEL macro, the interval timer interruption rou- 
tine of the task (to which linkage may have been 
extablished by an STXIT it macro) does not receive 
control. If the associated setime macro specified 
the same name of a TECB, that tecb's event bit is set 
on. If the macro is issued without an operand, the 
macro must not contain a comment unless the com- 
ment begins with a comma. 

UNLOCK Mmm 



Naate QperaticHa ^ Oj ^raiBf 



|naai«l UNLOCK ( (naiaeKS4t3iRe)](r)} jALL} 

The UNLOCK macro dequevte$ the issuing task (or 
partition) from the named resource, to which tile 
task had previously been enquetied via the lock 
macro. The resource laxist have been defined to the 
system by a dTl or gendtl macro, 

In addition, tiie unlock macro can be used to 
lower the lock control level Reduction of the lock 
control level may be done only if the tssxting task m 
currently locked, onto tine resource^ with the m.<M 
stringent ojnttoi level possible: CONTR.OL-E and 
tOCKOPT=i (the CONTROL and LOCKOPT parame- 
ters are described with the DTL macro). Ilb,e re- 
source then continues to be held by the task; howev- 
er, another task waitmg for this resowce can be dis* 
patched again and may or may not gain shared ac- 
cess (see also the description of the lock macro). In 
order to nse the Unlock macro for this purpose, the 
MODDTL macro must have been issued with the 
CHANGE operand set on. 

{saine|(S,nai&e)|(r)} : specifies the DTL address. 

ALL: frees ail resources which are locked by the 
task and whose DTL* were defined with Keep-no. If 
UNLOCK ALL is i^ued by the main task, not only the 
resources locked by that task are unlocked, but ako 



those which have been locked by subtasks, with 
owNER=PARTiTiON Specified for DTL generation. 

Return Codes in Register 15: 

Sacoessful request; the resource has been un- 
locked . 
4 The resource is not locked for the unlocking 

8 DTL format error. 

The UNLOCK ALL macro does not provide a re- 
turn code; register 15 remains unchanged. 



y IK lAU macro 


Name 


Operation 


Operand 


[name] 


VIRTAD 


(address|(l)} 



In s/370 mode, the virtad macro returns the virtual 
address corresponding to a specified real address. 

address|(l): Is the real storage address to be con- 
verted. It can be given as a symbol or in register 
notation. 

In ECPS:VSE mode, only a virtual address can be 
specified as input. The macro returns that same 
address. Register returns the virtual address only 
if: 

• for s/370 mode, the specified real address points 
to a page frame that contains a PFixed page, 

• for ECPS:VSE mode, the specified virtual address 

points to a PFixed page. 

Otherwise register contains 0. Thus, the macro can 
be used to test if a page is PFixed. 

Note: The pages of a program running in real mode are consid- 
ered to be fixed. 

WAITMacro 

Name Operation Operand 



[name] WAIT 



(ecbname|(I)) 



With the WAIT macro a task sets itself into the wait 
state until the specified event control block (ECB) is 
posted (bit of byte 2 turned on). Each task of the 
system can wait on any ECB within the same parti- 
tion. Do not use the wait macro for waiting on a 
telecommunication ECB, an RCB, or a CCB other than 
one that is associated with an I/O operation started 
in the same task. 

When a WAIT macro is processed in a multipro- 
gramming or multitasking environment, control is 
given to the supervisor, which makes the CPU avail- 
able to another task in the same or another partition. 
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One example of an ECB to be posted is the timer 
event control block (TECB) specified in the SETIME 
macro. The task issuing the wait remains in the 
wait state until the timer interval has elapsed (event 
bit in the TECB turned on). 

WAITM Macro 

Name Operation Operand 



[name] WAITM 



(ecb 1 ,ecb2, . . . | listname |( 1 )} 



The WAITM macro enables your program or task to 
wait for one of a number of events to occur. Control 
returns to the task when at least one of the ECBs 
specified in the WAITM macro is posted. 

The operand provides the addresses of the ECBs 
to be waited upon. The names of ecb 1, ecb2... are 
assumed when at least two operands are supplied. A 
maximum of 16 names can be coded. If one operand 
is supplied, it is assumed to be the name (listname) 
of a list of consecutive full- word addresses that point 
to the ECBS to be waited upon. The first byte follow- 
ing the last address in the list must be nonzero to 
indicate the end of the list. 

When control returns to a waiting task, register 1 
points to the posted ECB (byte 2, bit set on). Any 
fuUword can be used as ECB if bit of byte 2 of that 
word indicates a completed event. Examples of 
these blocks are CCBs and tecbs. However, a task 
never regains control if it is waiting for a CCB to be 
posted by another task's I/O completion. A MICR 
CCB gets posted only when the device stops, not 
when a record is read. Furthermore, telecommuni- 
cation ECBs and all RCBs must not be waited for 
because their format does not satisfy a wait or a 
WAITM (that is, bit of byte 2 would not be posted). 



XECBTAB Macro 



Name Operation Operand 



[name] XECBTAB TYPE= {DEFINE|DELETE1 

CHECK|RESET|DELETALL} 
,XECB=xecbname 
[,XECBADR= (xecbfieldi 

(S,xecbfield)i(rl)}] 
[,ACCESS= (XPOST IXWAIT) ] 
[,MFG= (area|(S,area)|(r2)}] 



You can use the XECBTAB macro only if XECB=YES 
was specified in the FOPT generation macro for su- 
pervisor assembly. The XECBTAB macro can be used 
(1) to define, for the specified cross-partition event 
control block (XECB), an entry in the supervisor's 
XECB table, (2) to delete such an entry, (3) to check 
for the presence of an entry, or (4) to reset an entry. 



An XECB for which an entry has been defined to the 
DOS/VSE supervisor can be referred to by XPOST and 
XWAIT macros; an xecb can be referred to also by a 
WAIT or WAITM macro if the task issuing the macro 
has previously defined the XECB (with 

ACCESS=XWAIT). 

TYPE= {DEFINE|DELETE|CHECK| 
RESET|DELETALL} 

The operand specifies the type of operation to be 
performed: 

DEFINE causes a new XECB table entry to be de- 
fined to the supervisor. 

DELETE causes an entry to be deleted from the 
supervisor's XECB table. type=delete can be speci- 
fied only for an XECB for which an entry has been 
defined previously in the same program. 

CHECK causes dos/vse to check whether or not 
an entry for a specific XECB has been defined al- 
ready. If that entry is present, specifying CHECK 
causes the address of both the xecb and the associ- 
ated XECB table entry to be returned. 

RESET causes dos/vse to clear the information in 
the supervisor XECB table that indicates which task 
communicates with the program having defined the 
XECB. TYPE=RESET can be specified only for an 
XECB for which an entry has been previously defined 
in the same program. 

After RESET, any task can attempt to establish a 
new connection with the owner. With 
ACCESS=XPOST, however, if the task currently con- 
nected to the XECB is issuing an xwait macro (at the 
time of RESET), this task will probably estabUsh con- 
nection again, nullifying the RESET operation. 

DELETALL performs three actions: 

• Causes all entries in the XECB table that were 
defined previously by the issuing task to be de- 
leted. 

• Breaks the communication between any XECB 
owner and the issuing task (that is, clears the 
information in the XECB table that indicates 
that the issuing task communicates with the 
XECB owner). 

• Post all tasks as ready-to-run that are waiting 
for an XPOST by the issuing task. If these tasks 
are XWAlTing on the XECB, they will get a re- 
turn code of X'08'. 

Note: If TYPE=DELETALL is specified, the XECB and AC- 
CESS operands must not be specified. XECBTAB with 
TYPE=DELETALL specified does not provide a return code; all 
registers remain unchanged. 

XECB=xecbname: specifies the name of the XECB. 
If the XECBADR operand is not present, xecbname is 
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the symbolic address of the 4-byte (or larger) XECB 
field. If, however, XECBADR is specified, xecbname 
is the name by which the control block is known 
between partitions; the symbolic address of the con- 
trol block field is given by XECBADR. 

The XECB field must be defined in your program, 
except when TYPE=CHECK is specified: in that case, 
the XECB field may be defined in another program. 

XECBADR=(xecbfield|(S,xecbfield)|(rl)}: 

XECBADR is used only if type=define is specified. 
It provides the symboUc address of the 4-byte (or 
larger) field that is to be used as XECB. 

ACCESS= (XPOST IXWAIT): This operand can 
be used together with type=define to specify 
whether the program will be allowed to post the 
XECB or wait for another program to do the posting. 

XPOST is assumed if the operand is omitted. It 
specifies that the program will be allowed to post the 
XECB . Specifying XPOST imphes that only one other 
active task is allowed to issue an XWAIT macro 
against the XECB. 

XWAIT specifies that the program will be allowed 
to wait for one other task to post the xecb. 

MFG= {area|(S,area)|(r2)} : The meg operand is 
required if the program that issues the xecbtab 
macro is to be reenterable. The operand specifies 
the address of a 64-byte storage area, that is, storage 
which your program obtains by a GETVIS macro. 
This area is needed for use by the system during 
execution of the macro. 

The MEG operand is only useful in conjunction 
with xecbaddr coded in either of the two notations 
(S,xecbfield) or (rl). 

Feedback Information 

Figure 5-8 shows the return codes that are supplied 
by DOS/vse in register 15. The illustration also indi- 
cates whether or not DOS/vSE returns the addresses 
of the pertinent XECB and the associated table entry 
in registers 1 and 14, respectively. 





X'OO' 


X'04' 


X'08' 


DEFINE 


XECB 
named is 
stored in the 
table * 


XECB named 
is already in the 
table ** 


The XECB ta- 
ble is full** 


DELETE 


XECB 

named is re- 
moved from 
the table ** 


XECB named 

was not found 

** 


The issuing 
program did 
not define the 
XECB ** 


CHECK 


XECB 

named was 
found in the 
table * 


XECB named 

was not found 

** 


N/A 


RESET 


named com- 
munication 

bytes cleared 

** 


XECB named 

was not found 

** 


The issuing 
program did 
not define the 
XECB ** 


* Register 1 contains the address of the XECB and register 
14 contains the address of the table entry. 

** Registers 1 and 14 are set to zero. 



Figure 5-8. XECBTAB feedback information. 



XPOST Macro 

Name Operation Operand 

[name] XPOST XECB={xecbname|(l)}, 

POINTRG=(l4) 



You can use the XPOST macro only if xecb=yes was 
specified in the FOPT generation macro for supervi- 
sor assembly. 

The XPOST macro provides for cross-partition 
communication by posting the specified XECB (the 
macro sets bit of byte 2 to 1). An XPOST macro 
issued against an XECB causes the task waiting for 
this XECB to be removed from the wait state (the 
waiting task may have issued an XWAIT, WAIT or 
WAITM with a previously defined XECB). This task 
may have been activated in the same or in another 
partition. 

If the XPOST macro is used in a main-line loop, 
the macro should be preceded by a test which en- 
sures that the other partition's task waiting for the 
event that is being posted must receive control and 
execute the function for which this event is a prere- 
quisite. 

To perform this test, a second xecb needs to be 
defined. This XECB allows the originally waiting 
task in its main-hne loop to post completion of its 
function as an event for which the originally posting 
task must wait. 

Resetting bit of byte 2 of the XECB is a user re- 
sponsibility. 
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Once a task has issued an XPOST macro for an 
XECB (with ACCESS=XWAIT), no Other task can issue 
an XPOST for this XECB, until the connection is end- 
ed. 

XECB= {xecbname|(l)}: specifies the name of the 
XECB to be posted. The name you specify must be 
the same as the one used to define the XECB. If reg- 
ister notation is used, the specified register must 
point to an 8-byte character field that contains the 
XECB name left-justified and padded with blanks. 
Do not specify 14 or 15 if you choose to use ordinary 
register notation. 

POINTRG=(14): specifies the register that points 
to the XECB table entry associated with the named 
XECB. Do not specify register 1 or 15 if you choose 
to use ordinary register notation. 

To obtain the address of the associated XECB ta- 
ble entry, issue earlier in the program an xecbtab 
macro for the same XECB and with type=CHECK or 
type=define specified. When DOS/VSE executes 
the XECBTAB macro, the system returns, in register 
14, the address of the pertinent XECB table entry. 
Figure 5-9, which shows a coding example for the 
use of the XWAIT macro, applies to the xpost macro 
accordingly. 

Note that if the POINTRG register contains (or 
any invalid value), all entries in the XECB table are 
searched to determine the correct address; no error is 
indicated. 

Return Codes 

When DOS/VSE returns control to the issuing task, 
register 15 contains one of the following return 
codes: 



XWAITMacro 



Name Operation Operand 



Return Code 

X'OO' 

X'04' 
X'OD' 



XOE' 



Meaning 

Successful completion, 
has been posted. 



The named XECB 



The named XECB has no associated table 
entry in the XECB table. 

The XECB referred to in the XPOST ma- 
cro was defined with ACCESS = XPOST 
specified in the XECBTAB macro, but the 
task that issued the XPOST macro does 
not own this XECB. 

The XECB referred to in the XPOST ma- 
cro was defined with ACCESS = XWAIT 
specified in the XECBTAB macro and ei- 
ther (1) the task that issued the XPOST 
macro also defined the XECB or (2) the 
XECB has been posted previously during 
the same execution by another task. 



[name] XWAIT 



XECB=(xecbname|(l)}, 
POINTRG=(14) 



You can use the xwait macro only if xecb=yes was 
specified in the fopt macro for supervisor assembly. 

The XWAIT macro enables the issuing task to wait 
for an XECB to be posted by another task that is exe- 
cuting in the same or in another partition. Control 
returns to the issuing task when the XECB is posted 
or if DOS/VSE detects an error condition. 

Once a task has issued an XWAIT macro for an 
XECB (with ACCESS=XPOST) to be posted, no other 
task can issue an XWAIT for this XECB, until the con- 
nection is ended. 

XECB= (xecbname|(l)) : specifies the name of the 
XECB, which may be defined in the same or another 
program. The name you specify must be the same as 
the one used to define the XECB. If register notation 
is used, the specified register must point to an 8-byte 
field that contains the name of the XECB left- 
justified and padded with blanks. Do not specify 
register 14 or 15 if you choose to use ordinary regis- 
ter notation. 

POINTRG=(14): specifies the register that points 
to the XECB table entry associated with the named 
XECB. Do not specify register 1 or 15 if you choose 
to use ordinary register notation. 

To obtain the address of the associated XECB ta- 
ble entry, issue earlier in the program an XECBTAB 
macro for the same XECB and with the TYPE=CHECK 
or TYPE=DEFINE Specified. When DOS/VSE executes 
the XECBTAB macro, the system returns, in register 
14, the address of the pertinent XECB table entry. 
Figure 5-9 shows a coding example for the use of the 
XWAIT macro; in that example, the required contin- 
uation character is not shown. The example assumes 
that the xecb was defined by a program executing 
in another partition by (source) instructions as fol- 
lows: 



XECBTAB 



MYECB 



DC 



TYPE=DEFINE, 
XECB=MYECB 



F'O' 



Note: Following the execution of an XPOST macro, register 1 
and 14 are set to zero. 
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WAITLP 


XECBTAB 


TYPE=CHECK, 
XECB=MYECB 




LTR 


15,15 




BNZ 


ERROR 




LA 


1 , XECBNAME 




XWAIT 


XECB= ( 1 ) , 
POINTRG= (14) 


XECBNAME 


DC 


CL8 ' MYECB 



Figure 5-9. Coding example showing the use of XECBTAB with 
TYPE=CHECK and of XWAIT. 



Note that if the pointrg register contains (or 
any invalid value), all XECBs are searched to deter- 
mine the correct address; no error is indicated. 



Return Codes 

When DOS/VSE returns control to the issuing task, 
register 15 contains one of the following return 
codes: 

Meaning 



Return code 

xoc 

X04' 
X08' 

X'OD' 



XOE' 



Successful completion. The named XECB 
has been posted. 



The named XECB has no associated table 
entry in the XECB table. 

The other task using this XECB has bro- 
ken communication without issuing an 
XPOST. 

The XECB referred to in the XWAIT macro 
was defined with ACCESS = XWAIT speci- 
fied in the XECBTAB macro, but the task 
that issued the XWAIT macro does not 
own this XECB. 

The XECB referred to in the XWAIT macro 
was defined with ACCESS = XPOST spec- 
ified in the XECBTAB macro and either 
(1 ) the task that issued the XWAIT macro 
also defined the XECB or (2) the task did 
not define the XECB, but another task is 
already waiting for the XECB to be 
posted. 



Note: Following the execution of an XWAIT macro, registers 1 
and 14 are set to zero. 
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